How to write documentation comments in ANSI C?

Question

I can't find how to write comments in C. I mean I know about // and /* */, what I mean is where can I find good practices? Like if I have a function, how do I write the @param variable is the value bla bla, like it is done in Java?

Are there any standards for this? Or can I just do it like I do it in Java?

Actually, you can't even use `//` in ANSI C. Only from C99 did they allow `//`. (Though GCC allows it as an extension.) — Mysticial, Jan 17 '12 at 05:10
The term "ANSI C" typically refers to the language described by the 1989 ANSI standard, but strictly speaking that's incorrect. In 1990, ISO issued the same standard (with some new introductory material and renumbered sections), and ANSI adopted it. In 1999, ISO issued a new C standard, and ANSI adopted it as well, rendering the 1989/1990 standard officially obsolete. In late 2011, ISO issued another new C standard, which ANSI has also adopted. Except for the first, C standards are initially published by ISO, not ANSI -- and it's best to refer to the standards by year. — Keith Thompson, Jan 17 '12 at 05:16
Alas, there are still compilers that don't support even the 1999 ISO C standard. Support for the 1990 standard is nearly universal. — Keith Thompson, Jan 17 '12 at 05:17
@KeithThompson Very true - compilers still don't implement C++89 - I did not know C was going for a revamp too - I've been concentrating on C++0x (or C++11 as its now known). Seems there are very little changes - what a waste of time. — Adrian Cornish, Jan 17 '12 at 05:25

score 13 · Accepted Answer · edited Jan 02 '19 at 04:58

13

There are many different standards, if you want to generate documentation, try doxygen

edited Jan 02 '19 at 04:58

Zac

185
2
17

answered Jan 17 '12 at 05:10

Dhaivat Pandya

6,499
4
29
43

score 12 · Answer 2 · edited Mar 24 '19 at 18:04

You can use javadoc standard and then use doxygen that understands javadoc to generate a documentation.

In doxygen I recommend using the option JAVADOC_AUTOBRIEF set to YES. If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the first line (until the first dot) of a Javadoc-style comment as the brief description.

Example for a class definition:

/**
 * A brief description. A more elaborate class description
 * @param bool somebool a boolean argument.
 * @see Test()
 * @return The test results
 */

(Some more examples in the doxygen manual)

Installation is really simple, there is a GUI and a nice graphical visualisation available with:

apt-get install doxygen doxygen-gui graphviz

Run the gui calling doxywizard and use the Wizard settings, only JAVADOC_AUTOBRIEF has to be set there in "Expert" settings.

score 5 · Answer 3 · edited Dec 26 '18 at 17:34

5

There are no standards follow the standard which your company mandates.
A popular way to create documentation from projects is to use doxygen.

edited Dec 26 '18 at 17:34

albert

8,285
3
19
32

answered Jan 17 '12 at 05:10

Alok Save

202,538
53
430
533

score 3 · Answer 4 · answered Jan 17 '12 at 05:12

3

An option is to use the doxygen format of writing comments - this has the added benefit of being able to generate html/latex and other sorts of docs for your code.

answered Jan 17 '12 at 05:12

Adrian Cornish

23,227
13
61
77

How to write documentation comments in ANSI C?

4 Answers4