On Wed, 29 Sep 2004 13:18:44 +0400, Vladimir Prus wrote > Hello, > there's one thing I don't like about reference doc produced by > Doxygen/BoostBook combination. Take a look at: > > http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/program_options.reference.html > > I'm I'm looking for a specific class or function, that reference is > very hard to use. First, it's organised by header, and the header > where a symbols is defined is secondary information for almost every > user
I agree totally with this, but header based documentation has been the boost way -- so we are fighting against tradition. For date-time we split the reference into 3 sections that coorespond to the 3 parts of the library: date_time for generic stuff, gregorian for dates, posix_time for times. Coming in 1.33 we will have a new section for local_time. http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/date_time.doxy.html Even with this though I don't feel the usability of the reference is very high. The google search on boost.org will, I think, be the one saving grace... >...snip... > > What I'd like is a reference organized as a list of symbols. A click > on each symbol would bring docs for that symbols. And the docs would > have to specify the header (for example: > http://www.boost.org/regression-logs/cs- > win32_metacomm/doc/html/options_description.html does not say which > header must be included). > > The 100% excellent solution would be something like Qt docs: > http://doc.trolltech.com/4.0/index.html. There are "All Classes", > "Main Classes", "Grouped classes" (almost what I've tried to do for > program_options), and "Annotated Classes". Yes this is nice. > I'm not sure how this could be implemented. For example, is it > possible to provide custom "reference index" page and a set of > BoostBook elements I can use to make various lists? > > For example, I would write: > > <section> > <title>Reference</title> > > <all-classes/> > <grouped-classes> > <group><class>Foo</class></group> > </grouped-classes> > </section> As you can see we did some separation in date_time, but it was a manual process. > Or, maybe, we can use the Doxygen @ingroup attribute? > > Is this reasonable idea? Could something like this be added? It would be really nice to be able to use @ingroup. I'm pretty certain that's how the QT folks are generating their structure. I've used this approach (without boost-book) for projects using doxygen -- the ability to specify an arbitrary grouping of elements and have a dedicated page in the documentation is a nice way of allowing the library authors to build a much more sophisticated and targeted reference guide. One key part of this is a symbol may appear in more than one group. That makes it much more flexible than namespace or other divisions. So in date-time, for example, you can imagine class day_clock showing up in a grouping of all available 'clock types' as well as showing up in a reference related to date programming. Jeff ------------------------------------------------------- This SF.net email is sponsored by: IT Product Guide on ITManagersJournal Use IT products in your business? Tell us what you think of them. Give us Your Opinions, Get Free ThinkGeek Gift Certificates! Click to find out more http://productguide.itmanagersjournal.com/guidepromo.tmpl _______________________________________________ Boost-docs mailing list [EMAIL PROTECTED] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
