kopia lustrzana https://github.com/Hamlib/Hamlib
98 wiersze
4.4 KiB
Plaintext
98 wiersze
4.4 KiB
Plaintext
Some tips on writing comments for the Doxygen documentation generator.
|
|
|
|
Doxygen is a flexible and powerful tool that not only reads and processes
|
|
specially formatted comments but also the actual code such as functions,
|
|
structures, enumerations, and defines. Sometimes it needs a few hints to
|
|
generate output in a consistent manner. As usual, there are multiple ways to
|
|
do one thing and it's likely that nearly all of them are present in the Hamlib
|
|
code base.
|
|
|
|
|
|
Markdown
|
|
|
|
Doxygen has supported the use of Markdown formatting elements in running text
|
|
for some time. Markdown has become rather universal over the past several
|
|
years for simple markup of text. It is widely supported by GitHub, Reddit, and
|
|
other Web sites. Those familiar with Markdown can use it the running Doxygen
|
|
comment text and it will be formatted as such in the output.
|
|
|
|
Common formatting is to emphasize text as italic, bold, or constant width font.
|
|
A string will be output in italics when it is has a single asterisk or
|
|
underscore preceding and succeeding the string, e.g. *italic*. Likewise the
|
|
string will be emboldened with two asterisks or underscores, e.g. **bold**. As
|
|
most text output will be in proportional text, a string surrounded by backticks
|
|
will be output in a constant width font, e.b. `constant width`.
|
|
|
|
|
|
Special commands
|
|
|
|
Doxygen will associate a comment block that immediately precedes the item. For
|
|
example, a comment block immediately precedes a structure declaration. It is
|
|
not necessary to include a line such as `\struct foo` in the comment block.
|
|
This is only necessary if the comment block must be separated from the item.
|
|
One example of the latter is a group of #define macros where the comment block
|
|
is placed above the group rather than interspersed. In this case, each #define
|
|
will need to be called out in the comment block with the \def command. The
|
|
choice is yours. Sometimes the source file will look more clean with a
|
|
separate comment block and at others interspersed comments will seem more
|
|
appropriate.
|
|
|
|
Notable exceptions are in the rotlist.h and amplist.h files where the #define
|
|
statements for the individual models have beem grouped together and the
|
|
comments grouped preceding them. This is true even in the case of a backend
|
|
with a single model as others may be added in the future. Including the \def
|
|
command in each comment block is appropriate.
|
|
|
|
Related to the previous section, sometimes a single comment will be appropriate
|
|
for a group of elements, particularly macros. An anonymous group will apply
|
|
the comment to all elements. The anonymous group uses the ///@{ and ///@}
|
|
constructs.
|
|
|
|
|
|
Reference links
|
|
|
|
Elements can be explicitly referenced with the # character. This is done in
|
|
running text to force Doxygen to create a link to the documentation for the RIG
|
|
handle, for example. Otherwise, it is rarely needed. Check the output as the
|
|
comment is being written and use the # character if needed.
|
|
|
|
Functions have two methods of forcing a reference. The first is to precede the
|
|
function name with a pair of colons, e.g. ::rig_init. This acts much like #
|
|
where it is sort of a hard instruction to Doxygen and a warning will be printed
|
|
if the function is not found in the list of files passed to Doxygen or it has
|
|
no associated comment. The second is to place a pair of parentheses
|
|
immediately after the function, e.g. rig_init(). This second construct is
|
|
preferred as Doxygen will not print a warning if the function is not found or
|
|
commented.
|
|
|
|
Links to external Web sites can be done in the Markdown syntax.
|
|
|
|
|
|
Code blocks in comments
|
|
|
|
Code blocks can be delimited with use of the \code and \endcode special
|
|
commands or with a Markdown "fence" which consists of three backticks on a line
|
|
preceding and succeeding the code block. Backticks are shorter to type.
|
|
|
|
|
|
Check the output
|
|
|
|
Always check the output to be sure it is what you want! I edit in one terminal
|
|
window, switch to another to run `make doc` from within the 'doc' directory and
|
|
reload the local page in the browser. This will show if a reference command is
|
|
required.
|
|
|
|
Be aware the members of an enumeration or structure cannot be linked to even
|
|
though they are documented. In that case, surround the member name with
|
|
backticks to render it in a constant width font.
|
|
|
|
|
|
What to document
|
|
|
|
For now the frontend part of the library is being documented. This includes
|
|
most files in `include/hamlib` and `src`. No decision has been made on
|
|
expanding this to the individual backends. That would be a Herculean task!
|
|
|
|
|
|
73, Nate, N0NB
|