Re: [Doxygen-users] Presumed brief?

[Ron W. <ron...@gm...>]

On Mon, Oct 7, 2013 at 9:01 AM, <dox...@li...
> wrote:

> Date: Mon, 7 Oct 2013 09:01:21 -0400
> From: John Yates <jo...@ya...>
> Subject: Re: [Doxygen-users] Presumed brief?
>
> The problems seem to be:
> - handling of C++ /// (to my mind the least obtrusive markup) seems
> inconsistent with other comment syntaxes.
>

While I don't know why, the designed behavior, in Doxygen, for /// is to
require at least a 2 line comment block. This is mentioned in Doxygen's
documentation.

(This is in contrast to ///< which seems to work just fine as a single line
comment block.)


> - autobrief is very line oriented.  I cannot seem to get an autobrief to
> span more than a single line and end at the first period.
>

This has worked for me in the past, but seems to be broken, now. The
documentation examples imply this should work.


> - the new MULTILINE_CPP_IS_BRIEF tag makes everything up to the first
> paragraph break into an autobrief.
>

Maybe this new feature also changed the previous "until first ." behavior?


> I have looked at the doxygen source code.  I am not surprised at my
> difficulties.  Decomposition of a block into brief and detailed components
> is implemented in the lexer's state machine.  That state machine has to
> handle properly every one of the many supported syntaxes.  I would have
> though a better design would be to collect a block ignoring any notion of
> autobrief.  At the end, after all documentation for all symbols had been
> collected, if autobrief is enabled and if a given symbol lacked an explicit
> brief description then I would simply define the brief description to be
> the initial text up to the first period or paragraph break.
>

I agree. This seems a more sensible way to handle parsing of comment
blocks.