Re: What's an annex? stratum?

[Robert Dewar <dewar@adacore.com>]

Joel Brobecker wrote:

> I think you misunderstood what Jim was saying. Jim documents his code
> very well, and gives examples of that. What he says is that it's a lot
> easier to maintain doco besides the associated code itself rather than
> maintain a separate document (which is pretty much what you argued for).
> Given the amount of resources that we have, this is probably the most
> pragmatic approach to keeping our code documented.

By all means I agree that it is better to have documentation as part of
the source files. Of course the effort of *producing* the initial
documentation is pretty much independent of whether the documentation
is in the source files or in separate files, so when I read:

> Time spent on the internals documentation has, itself, no effect on
> users' experience with GDB.  It's only worthwhile if that time, plus
> the time then spent doing something users *will* notice, is less than
> the time needed just to do something user-visible without internals
> documentation.

It is hard to read into this a viewpoint that says that time spent on
the internals documentation is OK if it is in the source files, but not
if it is in separate files.

I still read the above quoted para as questioning the value of internals
documentation, and to me such documentation is an essential part of any
complex piece of software. But certainly I apologize to Jim if I
misunderand his position.