Doxgen extracts comments from your code to generate documentation for users to use. The documents can be in various formats, such as html, rtf, xml, etc., but I just tested html, and it feels very good.
Doxgen is easy to get started with, and it takes less than two hours to master it. Using the Doxwizard GUI, you can easily set the document effect you need. After setting, it is OK to save it as a configuration file. Another advantage is that after a project team has set it up according to their own specifications, other people only need to Copy this configuration file, and if you want to generate a document to look at during the development process, then load it when running Doxywizard and it can be unified.
The setup is simple:
1. Set the output to html in Output and select the checkbox with frames and a navigation tree, so that the generated html document can see a browsing tree on the left;
2. Select the OUTPUT_LAGUAGE item as Chinese, so that the generated document can display the Chinese written in the code comments.
3. In order to facilitate the generation of instructions in Brief Description in the generated document, I manually changed the JAVADOC_AUTOBRIEF item in the configuration file and set it to YES. I did not find an interface to set this item in the DoxyWizard GUI, so I manually changed it. . The benefit of changing this is found in Ogre's code and documentation.
4. Finally, as long as the directory is set, it is OK.
Annotation aspects of writing code:
1. Usually the generated documents are for users to see, so use "//" or "/* */" for comments that do not need users to see, and use "///" or " /** */". And generally the comments that users need to see are written in *.h files.
2. The comment is written in front of the corresponding function or variable.
3. Common annotation methods: @remark is used for comments, @par is used for segmentation, @param is used to explain function parameters, and @return is used to explain function return values. "///" is used for Brief description, and "/** */" is used for Detailed description. After setting the JAVADOC_AUTOBRIEF mentioned above to YES, the first period in "/** */" The previous part is automatically used as the Brief description.
I can use this tool in the future, but I remember that when I read it a year ago, I felt that this thing was not as good-looking as the document generated by texi2html under Linux. Anyway, this is very convenient, and I will use it in the future. There are many functions that may be useful in the future.
Paste the picture of the document just generated, hehe, a sense of accomplishment...
