This is the mail archive of the
mailing list for the GDB project.
Re: What's an annex? stratum?
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
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.