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:
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.
Time spent on internal documentation facilitates others in doing
the work you describe as worthwhile. If the complaint is that there
are not many people working on GDB, part of the problem, speaking
from experience, is that GDB is fairly opaque. Flow of control
is convoluted. The organization of the code tries to be modular,
but that seems often more in the style than the substance.
The alternate "ask a question, we'll be happy to help" tends to
work better in theory than in practice. The answers seldom provide
much of an overview of operation in an area, nor do they provide the
detail which is commonly included in the documentation. Frequently,
the answers veer off on tangents (such as this discussion, which
started with a question about what's a stratum, still unanswered)
or into commentary (such as "the new scheme is much better").
I want to hear an internals documentation advocate say, "I'm going to
work on the internals documentation because I think the date at which
user-visible project X is complete will move closer when I do so."
The people who would most profit from improved documentation are
the people who are trying to understand the code. The people who
are best able to improve the documentation are the ones who have
experience with it.
If you look at improvement in GDB as a single-person effort, then
for the experienced person, it's always better to do it yourself
rather than take the time to facilitate someone less experienced.
If you look at it as a multi-person effort, where an expenditure
of effort on documentation will result in greater improvements
done by more people, then there's greater value.
I am *not* a seat-of-the-pants coder. Read prologue-value.h or
macrotab.h if you want to know my values. But I know that life is
short and uncertain, and that the pursuit of beauty has no regard for
that.
No one is pursuing beauty. This is the pursuit of utility.
--
Michael Eager eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306 650-325-8077