This is the mail archive of the libstdc++@gcc.gnu.org mailing list for the libstdc++ project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: [patch] Doxygen markup for 18, 19, part of 20



> > I also found that @param and @return commands were really useful, but
> the
> > @brief command was useless (there is a switch in the config file that
> will
> > autogenerate the equivalent, just like javadoc does).
> 
> I tried turning that on and stuff broke.  The other thing I don't like
> about
> it is that the person writing the comments has to pay special attention
> to the first sentence ("does this make sense on its own?") when writing
> a large block.

I personally find the @brief command useful. It gives finer control over
how the doc is formatted. Using @brief allows for multi-sentence brief
descriptions (useful when the first sentence is only 4 words or so). The
java autobrief function stops after the first period. 



Something I found that might be of interest (slightly off-topic for this
thread) is that it is possible to use groups without having to modify the
comment blocks inside the code.

For example doxygen provides @defgroup and @ingroup

It is possible to create files specifically for grouping only, say
"std_groups.doxygroup" with the following content


// std_groups.doxygroup

/** @defgroup GnuExtensions
 *
 *  @brief GNU extensions here
 *
 * More useful description of the group here
 */

/** @class specialFileBufThing
 *
 *  @ingroup GnuExtensions
 */

/** @class someExtension
 *
 *  @ingroup GnuExtensions
 */

--

If you add "*.doxygroup" to the pattern of files to process then the group
information will be processed. This allows the grouping of classes to be
done independently of the rest of the documentation and the grouping can be
rearranged with minimal effort when it needs to be modified.

Any documentation added inside the above blocks usually clobbers the real
doc so from what I've seen you can't put annotations in the grouping data.

--
Rich




Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]