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 00:55:35 +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>
- Reply-to: Eli Zaretskii <eliz at gnu dot org>
> 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>
>
> On Thu, Aug 8, 2013 at 10:26 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> >> Date: Wed, 07 Aug 2013 12:58:14 -0700
> >> From: Stan Shebs <stanshebs@earthlink.net>
> >> CC: gdb@sourceware.org
> >>
> >> > So how just declaring gdbint.texinfo dead and deleting it altogether?
> >>
> >> Isn't that going to be the end state of what I'm proposing? :-) I just
> >> added a path to conserve any bits that seem useful.
> >
> > My way is faster and easier.
>
> Possibly alright, but what final result do we want?
The same as now: the internals manual is useless.
> > 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?
> > Again, if we don't care about the documentation, then of course we
> > shouldn't care about poor information. If we do care, then wiki is a
> > way to waste resources at best.
>
> I disagree (that the wiki is a way to waste resources at best).
It is a waste because nothing good will ever come out of it. It will
be a heap of notes various people at various times thought it would be
a good idea to share. You cannot create a coherent document that way.
> > 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?
> > The net result will be that the documentation will be unreadable. Not
> > everybody who writes good code can write good documentation.
>
> OTOH, It's easier to improve documentation over time.
Who will do that, and why? Again, the core developers think that what
we have in the comments is enough, and if it is not enough, the
comments should be improved/expanded. Why would someone invest
efforts in another resource?