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]
Other format: [Raw text]

Re: [v3] doxygen module additions


> > This is a documentation only patch, but changed line numbers made
> > fixups in the testsuites for negative tests necessary.
> 
> <snip>
> 
> > Results are here:
> >
> > http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/modules.html
> 
> Taking a short look, I have noticed that the sequences (e.g.
> std::vector) nicely leave off the template<...> declaration except in
> the detailed description, while the algortihms put it there, making
> the overview page significantly less readable.

...yeah.

This pass was mostly trying to get the number of elements per page down
to the realm of the readable via coherent organization. 

> Is this a doxygen weakness or is there a way to influence this with
> markup ?

Short answer: I am not sure. 

Markup can be improved, without a doubt. It is hard to validate the
current markup, and doxygen errors when generating output are not
verbose enough about why entities with markup are not parsed in the
manner expected to be useful. 

Also, the doxygen configuration can be
changed to deal with @brief in multiple ways. (See
libstdc++-v3/doc/doxygen/user.cfg.in) But I don't see a way to specify
how to deal with template parameters in brief comments in either the
config or markup. Maybe I'm wrong about this though, as there are
certainly more expert doxygen users than myself.

More doxygen formatting options C++ for these longer, templatized member
functions would certainly be appreciated and used. Options that would be
useful: Template arguments on one line, return value on one line,
toggles for both.

Detailed formatting like this can probably be done via custom
stylesheets.

-benjamin


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