Re: [Consmgr-tech] doxygen doc formatting

[Geoff A. <gsa...@av...>]

On 2 Apr 2008, at 8:11 AM, Chris Ross wrote:

> [ discussion about multiple lines of //! vs. /*! ... */ elided ]

I see. That does all makes sense. The Doxygen format is a clear copy  
of the JavaDoc format, which uses /** ... */ for such things. But  
since Doxygen added the //! ... option, I just figured it worked the  
same way. But since each line beginning with // is a separate entity,  
I can see why it might not. However, Ruby's rdoc format is a little  
smarter, but it follows the ruby style, which is a little more  
flexible in general.

Anyway, got it.

>  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].

I'm surprised that's not a default. After using JavaDoc for years, I  
generally try to make the first sentence of such comments be a simple  
summary suitable for such purposes. What you described is exactly what  
JavaDoc does. And, in fact, the JavaDoc format specifies that there  
should (must, in fact, I think) be a first sentence, including a  
period, so that it can use that for the brief description.

- Geoff