[v3] initial Doxygen doc-generation support added

Phil Edwards pedwards@disaster.jaj.com
Fri Mar 30 16:05:00 GMT 2001


I let this message slip for too long.


On Mon, Mar 26, 2001 at 01:14:21AM +1000, Rich Churcher wrote:
> To be honest, I was a bit
> stumped as to what direction to take with the documentation given the
> discussion on maintainer vs. user documentation.  I'd like to ask that
> we define a bit more clearly what we're looking for in the way of user
> information, as I would still like to help with this.
> 
> Put another way, what do you see as "important, but lacking" in this
> area?

I... don't know.

Let me clarify:  since doxygen can do some kind of "only generate docs in
this section of code if we're in a certain mode[*]," then we can write
all kinds of comments in the code and they will only appear in the HTML
in maintainer-mode.  I can think of all /kinds/ of stuff I'd like to see
for that mode.

But for user documentation?  Grief, it's been too long since I was a "user"
to try and imagine what "they" want.  :-)  I think we could expose a list
of the public members.  No links back into the source code itself for
user mode, since that duplicates the source code and racks up diskspace.
Maybe no commentary or explanations, since that would be a /lot/ of typing
even if we weren't under the 3.0 deadline; if they want a detailed listing
they can plunk down $18 and get the very handy listing in the standard,
or plunk down a few more bucks and get the Jousuttis or Austern texts.
I for one don't feel like replicating their work from scratch without
getting paid for it...

Anyone?  Anyone?  What do y'all think of just listing public members for
J. Random User?  Maybe we can use this as a starting point for discussion.


Phil
[*]  At least, I'm pretty sure it can.

-- 
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.



More information about the Libstdc++ mailing list