Doxygen style comments: Difference between revisions
Munchgreeble (talk | contribs) Initial doxygen comments page |
Munchgreeble (talk | contribs) mNo edit summary |
||
| Line 1: | Line 1: | ||
TA Spring has automatically generated documentation for the source code which can be found [http://taspring.clan-sy.com/doxygen/ here]. The tool used for this is [http://www.doxygen.org doxygen]. Whilst doxygen does a good job of producing diagrams and extracting logical relationships from the code, the documentation can be somewhat hard to digest without any descriptive text to read! | TA Spring has automatically generated documentation for the source code which can be found [http://taspring.clan-sy.com/doxygen/ here]. The tool used for this is [http://www.doxygen.org doxygen]. Whilst doxygen does a good job of producing diagrams and extracting logical relationships from the code, the documentation can be somewhat hard to digest without any descriptive text to read! | ||
Therefore, please put doxygen style comments into the code | The good news is that doxygen can automatically extract your header comments from the code and use them as a description for the class/method/field they're associated with... as long as you stick to the doxygen comment style. Therefore, please put doxygen style comments into the code. | ||
Doxygen comments have the same syntax as Javadoc basically - if you're familiar with Javadoc, go ahead and write header comments as you normally would in Java. If you're not familiar with Javadoc, the main thing you need to know is to use: | |||
/** | /** | ||
At the start of your comment blocks ( | At the start of your comment blocks (doxygen also works with /*!). Or on the otherhand if you prefer using // style comments, use /// or //! as your comment marker. | ||
Within the comment blocks you can also use [http://www.stack.nl/~dimitri/doxygen/commands.html special commands] including the very useful @todo command. All @todo commands are noted by Doxygen and pulled out into a single "TODO" list page, which lists all the @todo items across the entire project in one place. | Within the comment blocks you can also use [http://www.stack.nl/~dimitri/doxygen/commands.html special commands] including the very useful @todo command. All @todo commands are noted by Doxygen and pulled out into a single "TODO" list page, which lists all the @todo items across the entire project in one place. | ||
| Line 11: | Line 13: | ||
The full [http://www.stack.nl/~dimitri/doxygen/manual.html doxygen manual] describes all the various commenting conventions you can use which doxygen will pick up. This includes nice things like being able to mark several items as having the same comment, producing lists, links into other classes/methods, how to use HTML within comments etc. | The full [http://www.stack.nl/~dimitri/doxygen/manual.html doxygen manual] describes all the various commenting conventions you can use which doxygen will pick up. This includes nice things like being able to mark several items as having the same comment, producing lists, links into other classes/methods, how to use HTML within comments etc. | ||
The current codebase (0.65b2) | The current codebase (0.65b2) contains non doxygen comments as we've only just started using it. If you do see header/field comments which start with just /* or //, please do a search-and-replace on them so that we can have the benefit of them in the documentation. Thanks | ||
Revision as of 23:46, 18 October 2005
TA Spring has automatically generated documentation for the source code which can be found here. The tool used for this is doxygen. Whilst doxygen does a good job of producing diagrams and extracting logical relationships from the code, the documentation can be somewhat hard to digest without any descriptive text to read!
The good news is that doxygen can automatically extract your header comments from the code and use them as a description for the class/method/field they're associated with... as long as you stick to the doxygen comment style. Therefore, please put doxygen style comments into the code.
Doxygen comments have the same syntax as Javadoc basically - if you're familiar with Javadoc, go ahead and write header comments as you normally would in Java. If you're not familiar with Javadoc, the main thing you need to know is to use:
/**
At the start of your comment blocks (doxygen also works with /*!). Or on the otherhand if you prefer using // style comments, use /// or //! as your comment marker.
Within the comment blocks you can also use special commands including the very useful @todo command. All @todo commands are noted by Doxygen and pulled out into a single "TODO" list page, which lists all the @todo items across the entire project in one place.
The full doxygen manual describes all the various commenting conventions you can use which doxygen will pick up. This includes nice things like being able to mark several items as having the same comment, producing lists, links into other classes/methods, how to use HTML within comments etc.
The current codebase (0.65b2) contains non doxygen comments as we've only just started using it. If you do see header/field comments which start with just /* or //, please do a search-and-replace on them so that we can have the benefit of them in the documentation. Thanks
