[Doxygen-users] Presumed brief?

[John Y. <jo...@ya...>]

Greatly influenced by emacs documentation conventions I strive for a
lightweight, prose-oriented methodology.  A crucial guiding principle is
DNRY (Do Not Repeat Yourself).  I never use mark up tokens (e.g. \brief,
\fn, \param, etc) because:
1) they consume ridiculous amounts of precious vertical space
2) they require repeating names already available from the source (violating
DNRY)
3) they scream "marked up"

My typical function looks like:

int foo
    /// A sentence which constitutes a brief statement of the
    /// function's significance
    ( bool x    ///< A brief description
    , char y    ///< Another brief description
    , long z    ///< Yet another brief description
    )
{
    ...
}

Often all I provide is a one line brief description of my function. 
Sometimes it fits on one line; sometimes it does not.  Most times I remember
the final period; sometime I forget.

Sometimes I amplify my description.  In such cases the first (brief
description) sentence definitely ends with a period (though not necessarily
on the first line).  The amplification is written as a logical continuation
of that brief description.  Hence when presenting a detailed description I
do not want to omit that introductory opening first sentence.

What I would really like is for doxygen to assume that any documentation
block is at least a brief description.  If it contains no period or if a
period is not followed by additional text then there is only a brief
description and nothing more.  In such cases I would really like doxygen to
suppress its "More..." link rather than suggest incorrectly that more
documentation is available.

If a documentation block contains a period followed by additional text
(whether or not that period falls on the first line) then I would like
doxygen to interpret the entire block from start to finish as a detailed
description.

I have experimented with various doxygen contral setting attempting to
achieve this behavior.  As best as I can tell it is not possible to achieve
this behavior.  Am I correct?  Or have I missed something?

/john



--
View this message in context: http://doxygen.10944.n7.nabble.com/Presumed-brief-tp6315.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.