This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: Documentation generated from sources proposal
- From: Mark Kettenis <mark dot kettenis at xs4all dot nl>
- To: jan dot kratochvil at redhat dot com
- Cc: gdb at sourceware dot org
- Date: Tue, 27 Oct 2009 08:17:05 +0100 (CET)
- Subject: Re: Documentation generated from sources proposal
- References: <20091012161424.GA20603@host0.dyn.jankratochvil.net>
> X-SWARE-Spam-Status: No, hits=-2.5 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS,SPF_PASS
> Date: Mon, 12 Oct 2009 18:14:24 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
>
> Hi,
>
> currently there is gdb/doc/gdbint.texinfo referencing gdb/ sources functions
> and duplicating various comments in the gdb/*.c sources. At the same time the
> gdb/doc/gdbint.texinfo content is obsolete and one usually misses it when
> dealing with the sources.
>
> May the GDB project start using some tool to format documentation from the
> sources? One could move the appropriate parts of gdb/doc/gdbint.texinfo into
> gdb/*.c along the patches being submitted, keeping in gdb/doc/gdbint.texinfo
> only the abstract parts in the future.
>
> This proposal was already discussed in the past.
I'm not a big fan of this sort od documentation for three reasons:
1. It makes it harder to write documentation in the code since you
need to use the proper markup commands. And depending on the tool
used for this there may be restrictions on how comments have to be
structured.
2. It makes it harder to read comments in the source code, since they
will contain all sorts of distracting markup.
3. In my experience the approach usually leads to fairly useless
documentation.