Re: Documentation generated from sources proposal

[Mark Kettenis <mark.kettenis@xs4all.nl>]

> 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.