[Consmgr-tech] doxygen doc formatting

[Chris R. <cro...@di...>]

   Hey there.  I've seen you, once or twice, do:

//! This is a paragraph describing something.  We put
// text here, and expect it to be used by doxygen.  Is
// that reasonable?

   This only sets the first line to doxygen.  "//!" is a
one-line comment, or in a block treated as a block.  So,
the above should be:

//! This is a paragraph describing something.  We put
//! text here, and expect it to be used by doxygen.  Is
//! that reasonable?

   or, the format I've been using for block comments:

/*! This is a paragraph describing something.  We put
  * text here, and expect it to be used by doxygen.  Is
  * that reasonable?
  */

   I've turned on a feature called "QT_AUTOBRIEF" in the doxygen  
configuration.  That will cause QT style comments (which /*! ...... */  
is, but I think //! in a group isn't.  I'm not 100% sure on that, but)  
to absorb the first sentence (til a period) as the "brief" comment,  
and the remainder as a detailed comment.  I *think* if you were to use  
the first of my suggestions above, the entire block of text would be  
taken as a detailed comment, and there would be no brief comment.  The  
brief comment is what gets displayed next to the class/file/method/etc  
in the list forms, and the detail all gets put lower on the pages  
where it gives a block explaining each thing [in detail].

   Anyway.  Let me know if what I've described here makes sense.  I  
don't expect you to necessarily take all of this in, and I'm happy to  
have that responsibility myself, but I figure you want to know the  
details that matter as you go.  :-)

   Thanks!

                               - Chris