Hi John, You can use MULTILINE_CPP_IS_BRIEF=YES and JAVADOC_AUTOBRIEF=NO
/// A brief description that /// spans multiple lines. /// /// More details follow. or you can use MULTILINE_CPP_IS_BRIEF=NO and JAVADOC_AUTOBRIEF=YES /// A brief description that /// spans multiple lines. /// More details follow. In the latter case you should always have at least 2 ///'s if you want a detailed description. A single line with /// is always a brief description. I think this provides enough flexibility and I don't want to make things even more complex. Regards, Dimitri On Oct 7, 2013, at 15:01 , John Yates <j...@yates-sheets.org> wrote: > 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 ------------------------------------------------------------------------------ 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=60134071&iu=/4140/ostg.clktrk _______________________________________________ Doxygen-users mailing list Doxygen-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/doxygen-users
