Re: libstdc++ Documentation

[Phil Edwards <pedwards at disaster dot jaj dot com>]

On Sat, Mar 17, 2001 at 01:02:05PM -0800, Greg Bumgardner wrote:
> handling generated/configured code, I normally run doxygen after I configure
> and build a library, so doxygen doesn't need to know anything about
> configuration-specific files.  This may not be appropriate for generating
> cross-configuration design documentation, but should provide satisfactory
> end-user documentation.

What I've been playing with are two modes, one for users and one for
maintainers:

    76% s
    total 168
    drwxr-xr-x    2 pme      pme          4096 Dec  9 23:41 CVS/
    drwxrwxr-x    2 pme      pme         90112 Mar 16 16:32 html_maint/
    drwxrwxr-x    2 pme      pme          4096 Mar 16 15:49 html_user/
    -rw-r--r--    1 pme      pme         29211 Mar 16 16:32 maint.cfg
    -rwxr-xr-x    1 pme      pme          2016 Mar 16 16:00 run_doxygen*
    -rw-r--r--    1 pme      pme         29178 Mar 16 16:32 user.cfg
    77% du html*
->  17M     html_maint
->  24k     html_user
    78% diff maint.cfg user.cfg
    49,50c49,50
    < #EXTRACT_ALL            = NO
    < EXTRACT_ALL            = YES
    ---
    > EXTRACT_ALL            = NO
    > #EXTRACT_ALL            = YES
    55c55
    < EXTRACT_PRIVATE        = YES
    ---
    > EXTRACT_PRIVATE        = NO
    68c68
    < HIDE_UNDOC_MEMBERS     = NO
    ---
    > HIDE_UNDOC_MEMBERS     = YES
    75c75
    < HIDE_UNDOC_CLASSES     = NO
    ---
    > HIDE_UNDOC_CLASSES     = YES
    212c212
    < GENERATE_TODOLIST      = YES
    ---
    > GENERATE_TODOLIST      = NO
    218c218
    < GENERATE_TESTLIST      = YES
    ---
    > GENERATE_TESTLIST      = NO
    273c273
    < INPUT                  = include src libmath libsupc++ libio config
    ---
    > INPUT                  = include src
    369c369
    < HTML_OUTPUT            = html_maint
    ---
    > HTML_OUTPUT            = html_user
    79%

As you can see from the timestamps on the files; I've gotten this far and
no further; the next step would be to add some actual documentation (in the
sense of "doxygen-aware documentation") to the sources and start looking
at the results.  Higher-priority issues have pushed this down my task stack.

The config files were originally copies of the one used by AbiWord.

I've been wanting to be able to do this without needing a build directory
in place already (hence, no information produced by configure/make should
be required).  Thus the script you see there.  There's a "doxygen" target
in the top Makefile, but it just runs the script.

There's also a question that we need to consider; I'll raise it below.


> I agree that it will likely be somewhat difficult retrofitting the current
> V3 code base to support doxygen-based code generation. It's not to difficult
> to get good results when you code for doxygen from the very beginning, but
> it is probably quite a bit more work doing it after-the-fact. 
> 
> As for embedding documentation, I also agree that this is a monumental task.
> If such an attempt were made, the docs should probably just be lifted from
> the standard (I don't recall seeing a copyright on the standard itself).

Let's see if I can get acroread to give me that little text-selection
thingy... ah yes.  Okay, here's the blurb on the cover page:

#    Copyright 1998 by Information Technology Industry Council (ITI). All
#    rights reserved. These materials are subject to copyright claims
#    of International Standardization Organization (ISO), International
#    Electrotechnical Commission (IEC), American National Standards Institute
#    (ANSI), and Information Technology Industry Council (ITI). Not for
#    resale. No part of this publication may be reproduced in any form,
#    including an electronic retrieval system, without the prior written
#    permission of ITI. All requests pertaining to this standard should be
#    submitted to ITI, 1250 Eye Street NW, Washington, DC 20005.

Naturally we can quote certain chunks under "fair use;" we do it on the
newsgroups all the time.


> > -----Original Message-----
> > From: Victor Kirk [mailto:vic.kirk@btinternet.com]
> > Sent: Wednesday, March 14, 2001 1:06 PM
> > To: libstdc++@gcc.gnu.org
> > Subject: Re: libstdc++ Documentation

Eeek.  I never saw this message.  Quick replies:


> > Besides, I spend the majority of my development behind a firewall and
> > don't want to buy two copies of each book I own.

I buy one copy, and a sturdy backpack.  :-)  The cheapest reference I own
is the Standard itself (ah, sweet sweet searchable PDF).


> > Companies I have been interviewed by have actually said that they 
> > dont use the STL because their developers dont understand it. I 
> > seriously doubt that their developers are incapable of understanding.

They should seriously get a copy of Matt Austern's book.  No other text
I've seen stresses the "concept" part of the STL so much.


> > >its support for templates is limited -- not an asset with a template
> > >library.
> > I agree with this, I breifly ran doxygen on the files yesterday and
> > can say the results where far from staisfactory (this was not 
> > using the
> > config file provided by Stephen).  Although I'm sure it could 
> > be improved upon.

Well, you're seeing stuff generated from the source, and no actual
documentation strings in there.  :-)  One of the things we need to decide
before going much further is:  how many of the "details" do we want
to expose, even to the maintainers?  There are a /bunch/ of things like
_vector_alloc_Base and whatnot that, frankly, I don't give a fat rat's ass
about reading the docs for.  Or even documenting in the first place, for
that matter.  Other details, like the behind-the-scenes pieces of codecvt,
I consider very critical.

One of the things I want to be able to do in the script is remove/strip
unneeded documentation from the HTML.


Phil

-- 
pedwards at disaster dot jaj dot com  |  pme at sources dot redhat dot com
devphil at several other less interesting addresses in various dot domains
The gods do not protect fools.  Fools are protected by more capable fools.