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?

Answer 1

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

Answer 2

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

Answer 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.

Answer 4

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.