Re: Fw: Documenting V3 internals

[Rich Churcher <churcher at ihug dot com dot au>]

> | Gabriel Dos Reis <Gabriel.Dos-Reis@cmla.ens-cachan.fr> writes:


> | The idea of not providing as much detail as is available
> | on library internals strikes me as an attitude more suited 
> | to a commercial project than an open source effort.
>
> That is a silly argument.
>
> Not just because it is open source means we should overlook sound
> software engineering practices.  Telling users how we happen to
> implement class X at YY:MM:DD:hh:mm:ss doesn't buy them and us
> anything at all.  That idea violates the principle of leats
> commitment we're contracting through interfaces; it violates
> encapsulation.  In the end, implementors and users will be locked
> into a particular implementation.  All users need to know about the
> library is its interface semantics.

I think you may have misunderstood me, or perhaps I expressed the idea
poorly.

I'm not suggesting we abandon good design.  This kind of project
attracts people who are interested in what goes on "under the hood".
I include myself in that category - I would be delighted with
documentation that described libstdc++ internals in detail, even
though I'm only an amateur and don't get paid to do this sort of
thing.

However, I recognise your concern and I like the idea of separating
general user docs and internals docs.  I'm happy to work on helping
to provide a documentation set that describes behaviour, as you
suggest.


> | Let's put it another way - what areas of the project do 
> | you see as being poorly documented at this time, and what 
> | kind of documentation would you provide to correct the 
> | problem?
>
> From the top of my head:
> 1) mini howtos to moving from v2 to v3.
> 2) installation configurations
> 3) howto to use locales, etc.

What was your opinion of the idea to provide a set of documentation
centred around the standard headers?

-- 
Cheers,
Rich.