How to write documentation comments in ANSI C? [closed]
-
17-04-2021 - |
Pregunta
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?
Solución
There are many different standards, if you want to generate documentation, try doxygen
Otros consejos
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.
There are no standards follow the standard which your company mandates.
A popular way to create documentation from projects is to use doxygen.
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.