Re: Documenting V3 internals

[Gabriel Dos Reis <Gabriel dot Dos-Reis at cmla dot ens-cachan dot fr>]

Jason Merrill <jason@redhat.com> writes:

| >>>>> "Rich" == Rich Churcher <churcher@ihug.com.au> writes:
| 
| > Gabriel Dos Reis <Gabriel.Dos-Reis@cmla.ens-cachan.fr> writes:
| > [ snip ]
| >> Users should not concern themselves with the library's internals -- all
| >> they need is the library's observable behaviour.  Users have no
| >> business in knowing how we actually provide the services contracted
| >> through the interfaces.  As such, there is no point in providing users
| >> with any documentation mentioning which internal files do which jobs.
| 
| > 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.
| 
| I agree.  The more extensive the documentation, the better, though I
| certainly wouldn't object to separating the usage and implementation
| sections (as in the GCC documentation).

I'm not objecting to documenting V3.  I'm objecting to what is being
put in the documentation.  Even in the GCC documentation, we don't
document how exactly trees happen to be implemented; what we
publically document are their observable behaviours.

-- Gaby