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.
------------------------------------------------------------------------------
October Webinars: Code for Performance
Free Intel webinars can help you accelerate application performance.
Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from
the latest Intel processors and coprocessors. See abstracts and register >
http://pubads.g.doubleclick.net/gampad/clk?id=60134791&iu=/4140/ostg.clktrk
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
