A complete list of `@xxx` commands can be found at http://www.doxygen.nl/manual/commands.html.
@ -158,44 +167,73 @@ To describe a class, use the same construct above the class definition:
* @see GetWarnings()
*/
class CAlert
{
```
To describe a member or variable use:
```c++
int var; //!<Detaileddescriptionafterthemember
//! Description before the member
int var;
```
or
```c++
//! Description before the member
int var;
int var; //!<Descriptionafterthemember
```
Also OK:
```c++
///
/// ... text ...
/// ... Description ...
///
bool function2(int arg1, const char *arg2)
```
Not OK (used plenty in the current source, but not picked up):
Not picked up by Doxygen:
```c++
//
// ... text ...
// ... Description ...
//
```
Also not picked up by Doxygen:
```c++
/*
* ... Description ...
*/
```
A full list of comment syntaxes picked up by Doxygen can be found at http://www.doxygen.nl/manual/docblocks.html,
but the above styles are favored.
Documentation can be generated with `make docs` and cleaned up with `make clean-docs`. The resulting files are located in `doc/doxygen/html`; open `index.html` to view the homepage.
Recommendations:
Before running `make docs`, you will need to install dependencies `doxygen` and `dot`. For example, on macOS via Homebrew:
```
brew install graphviz doxygen
```
- Avoiding duplicating type and input/output information in function
descriptions.
- Use backticks (``) to refer to `argument` names in function and
parameter descriptions.
- Backticks aren't required when referring to functions Doxygen already knows
about; it will build hyperlinks for these automatically. See
http://www.doxygen.nl/manual/autolink.html for complete info.
- Avoid linking to external documentation; links can break.
- Javadoc and all valid Doxygen comments are stripped from Doxygen source code
previews (`STRIP_CODE_COMMENTS = YES` in [Doxyfile.in](doc/Doxyfile.in)). If
you want a comment to be preserved, it must instead use `//` or `/* */`.
### Generating Documentation
The documentation can be generated with `make docs` and cleaned up with `make
clean-docs`. The resulting files are located in `doc/doxygen/html`; open
`index.html` in that directory to view the homepage.
Before running `make docs`, you'll need to install these dependencies:
fanquake
5 years ago