Re: [Doxygen-users] Presumed brief?

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

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
<Gre...@do...>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:jo...@ya...]
> > Sent: 05 October 2013 16:14
> > To: dox...@li...
> > 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
> > Dox...@li...
> > 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
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>