How to write documentation comments in ANSI C? [closed]

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

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.