This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: What's an annex? stratum?
Jim Blandy wrote:
Robert Dewar <dewar@adacore.com> writes:
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.
You're right; this doesn't make sense as written.
I write the comments in the code before I write the code, because I've
found that the effort of trying to explain what I'm about to try to do
helps clarify my own understanding a great deal. For me, at least, it
makes enough of a difference that I'm sure I come out ahead, if you
include debugging time.
I find the same thing, and even more these days, I find I can't rely
on my memory so well, so if I come back to code I wrote 6 months ago,
I need the documentation as much as anyone :-)
In other words, if the internals documentation is written before the
code, then, for me, it is a worthwhile investment. In that case, I do
believe that writing that documentation brings the completion date
closer, and I write it. I don't know whether other contributors need
this particular crutch; I'm pretty sure some don't.
The only other time I write explanations is when someone asks for
help; here, again, the investment is worthwhile, because someone is
about to go off and write some code, and I can bring their completion
date closer. Most of what I've contributed to gdbint.texinfo got in
there because Eli liked something I'd written on the mailing list and
asked me to put it there.
certainly fair enough.
One thing that I have found helpful is to ask newcomers to report
as bugs cases in which the code is not clear, and then when the
explanations are given, or the detective work completed, help
write the documentation they found missing.