Greg,
Thanks for the reply. (And thanks for correcting those typos in my final
paragraph :-).
Yes, I am familiar with all three of those settings. And today I actually
get vaguely useful output from doxygen.
The problems seem to be:
- handling of C++ /// (to my mind the least obtrusive markup) seems
inconsistent with other comment syntaxes.
- 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.
- the new MULTILINE_CPP_IS_BRIEF tag makes everything up to the first
paragraph break into an autobrief.
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.
/john
On Mon, Oct 7, 2013 at 3:46 AM, Greg Aldridge
<greg.aldri...@domino-uk.com>wrote:
> Without knowing what "various document control settings" you've
> experimented with it's difficult to make suggestions or guess how well
> you've read the manual (or even the comments in the default config file).
>
> If you have read the manual (or comments) you'll already know about these:
> <
> http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_javadoc_autobrief
> >
> <http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_repeat_brief>
> &
> <
> http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_always_detailed_sec
> >
>
> Greg.
>
> > -----Original Message-----
> > From: John Yates [mailto:j...@yates-sheets.org]
> > Sent: 05 October 2013 16:14
> > To: doxygen-users@lists.sourceforge.net
> > Subject: [Doxygen-users] Presumed brief?
> >
> > 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
>
>
> ****************************************************
> Visit our website at http://www.domino-printing.com
> ****************************************************
> This Email and any files transmitted with it are intended only for the
> person or entity to which it is addressed and may contain confidential
> and/or privileged material. Any reading, redistribution, disclosure or
> other use of, or taking of any action in reliance upon, this information by
> persons or entities other than the intended recipient is prohibited. If
> you are not the intended recipient please contact the sender immediately
> and delete the material from your computer.
>
> E-mail may be susceptible to data corruption, interception, viruses and
> unauthorised amendment and Domino UK Limited does not accept liability for
> any such corruption, interception, viruses or amendment or their
> consequences.
> ****************************************************
> Domino UK Limited. Registered in England. Registered Number:1750201.
> Registered Office Address: Trafalgar Way, Bar Hill, Cambridge, CB23 8TU.
>
>
>
>
> ------------------------------------------------------------------------------
> 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
>
------------------------------------------------------------------------------
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
