[Doxygen-users] Re: Doxygen Guidelines for Developers (Kevin Hudson)

[Kevin H. <Kev...@Ca...>]

We just implemented new documentation standards at our company a month ago.
Initially acceptance was guarded. After all, creating structured comments is
a lot of work. However, we have management support. Only new code, changes
to declarations, and changes to implementations, require structured
comments. This lets us work towards fully commented code incrementally. Our
biggest problem is correct spelling of the tags. In the near term, we intend
to modify our filter program to handle close matches automatically. 

I think the most important thing we did was to specify structured comments.
Uncommented source code lacks three essential elements: an explanation of
the semantics, the constraints, and usage instructions. Our standard
specifies how to comment the first two. Usage is handled in external
documentation. Additional comments are done using standard C++ comments. We
only permit a small set of tags. Additional formatting is not permitted,
that's the job of the style sheets.

For each programmatic construct, class declaration, function declaration,
macro definition, etc., we specified which tags are required, and which are
optional. We attempted to make things as intuitive as possible. The comments
look something like this:
/*!
\brief
    Free method defining a template function to perform default
    comparison between objects. Should be overridden for classes
    where compare is a complex procedure and time could be saved
    by avoiding the extra test
\tparam T
    The objects for comparison.  The template class must provide for
    operator==() and operator<().
\precondition a
    The left parameter of the comparison
\precondition b
    The right parameter of the comparison
\postcondition result
    a < b returns -1,  a == b returns 0,  a > b returns 1
*/
template <class T> int compare (const T &a, const T &b)

We decided to use non-standard Doxygen tags, and convert them to standard
Doxygen tags with a filter program. For example, the tag "\tparam" would
convert to "\par Template Parameter". Here are the tags we use, and the
Doxygen tags the filter program substitutes. Only a few tags are commonly
used. Additional tags are not permitted so we could use other tools in the
future (as if anything could rival Doxygen).

"accesslist"    "par AccessList" // for friend declarations, describes what
the friend accesses
"algorithm"     "par Algorithm" // algorithm description 
"brief"         "brief" 
"complexity"    "par Complexity" // function complexity O(logN)
"definition"    "par Definition" // for terms
"docs"          "par Documentation" // name of supporting documentation
"frequency"     "par Frequency" // how frequently function is called
"guarantee"     "par Exception Guarantee" // basic, strong, succeeds,
neutral 
"invariant"     "par Invariant" 
"mparam"        "par Macro Parameter" 
"note"          "par Note" 
"pattern"       "par Design Pattern" 
"postcondition" "par Postcondition" // we consider return values to be
postconditions
"precondition"  "par Precondition" // we consider parameters to be
preconditions
"priority"      "par Priority" 
"threadsafe"    "par Threadsafe" 
"tparam"        "par Template Parameter"