[Consmgr-tech] doxygen doc formatting
Status: Alpha
Brought to you by:
cross
|
From: Chris R. <cro...@di...> - 2008-04-02 12:11:30
|
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
|