This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: A new strategy for internals documentation
- From: Eli Zaretskii <eliz at gnu dot org>
- To: Doug Evans <dje at google dot com>
- Cc: stanshebs at earthlink dot net, gdb at sourceware dot org
- Date: Fri, 09 Aug 2013 12:12:37 +0300
- Subject: Re: A new strategy for internals documentation
- References: <5201781A dot 3000607 at earthlink dot net> <83k3jyunt8 dot fsf at gnu dot org> <5202A6D6 dot 8090908 at earthlink dot net> <83li4ct7ot dot fsf at gnu dot org> <CADPb22ToXn8aypnpyHEFrUw_yQQiib=ieCj7WbQLSaZQM00RVg at mail dot gmail dot com> <8361vfu9t4 dot fsf at gnu dot org> <CADPb22QNbWQhPGQ2Utfh=C+hFH5iJMrR30G=BE646Z87R_1Yfg at mail dot gmail dot com>
- Reply-to: Eli Zaretskii <eliz at gnu dot 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.