This is the mail archive of the gdb@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]