Re: A new strategy for internals documentation

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 8 Aug 2013 16:04:49 -0700
> From: Doug Evans <dje@google.com>
> Cc: Stan Shebs <stanshebs@earthlink.net>, gdb <gdb@sourceware.org>
> 
> On Thu, Aug 8, 2013 at 2:55 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> >> Date: Thu, 8 Aug 2013 14:07:51 -0700
> >> From: Doug Evans <dje@google.com>
> >> Cc: Stan Shebs <stanshebs@earthlink.net>, gdb <gdb@sourceware.org>
> > [...]
> >> > The grumbles come from people other than those who can provide the
> >> > documentation.  And the latter don't think we have a problem in the
> >> > first place.
> >>
> >> If the latter includes me I disagree.
> >
> > Disagree with what, and why?
> 
> I disagree with the statement "the latter don't think we have a problem".
> We do have a problem: I think our internals documentation needs improving.

Then you seem to belong to the same minority as I do.

> >> > Why do you need development for comments?
> >>
> >> He's referring to development of the comment->doc generator.
> >
> > Why do we need that developed, if it already does the job?
> 
> Assuming it doesn't have latent bugs that no one has tripped over yet,
> and assuming it does everything we want, now and tomorrow.

What is good enough for libiberty and binutils ought to be good enough
for us.

> I'm one that thinks that there is not enough, and that expanding the
> comments is not enough.  For one there's a higher level / descriptive
> view that's missing with that approach.  Plus the S/N ratio when faced
> with reading all the source code is much lower than when able to
> browse something generated from the comments in the code.

I think the same, but others don't, as was demonstrated numerous times
in past discussions.