From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <gdb-return-36112-listarch-gdb=sources.redhat.com@sourceware.org>
Received: (qmail 29759 invoked by alias); 27 Oct 2009 07:17:30 -0000
Received: (qmail 29640 invoked by uid 22791); 27 Oct 2009 07:17:27 -0000
X-SWARE-Spam-Status: No, hits=-2.5 required=5.0 	tests=AWL,BAYES_00
X-Spam-Check-By: sourceware.org
Received: from sibelius.xs4all.nl (HELO glazunov.sibelius.xs4all.nl) (83.163.83.176)     by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 27 Oct 2009 07:17:23 +0000
Received: from glazunov.sibelius.xs4all.nl (kettenis@localhost [127.0.0.1]) 	by glazunov.sibelius.xs4all.nl (8.14.3/8.14.3) with ESMTP id n9R7H7a2018155; 	Tue, 27 Oct 2009 08:17:07 +0100 (CET)
Received: (from kettenis@localhost) 	by glazunov.sibelius.xs4all.nl (8.14.3/8.14.3/Submit) id n9R7H58K006139; 	Tue, 27 Oct 2009 08:17:05 +0100 (CET)
Date: Tue, 27 Oct 2009 10:07:00 -0000
Message-Id: <200910270717.n9R7H58K006139@glazunov.sibelius.xs4all.nl>
From: Mark Kettenis <mark.kettenis@xs4all.nl>
To: jan.kratochvil@redhat.com
CC: gdb@sourceware.org
In-reply-to: <20091012161424.GA20603@host0.dyn.jankratochvil.net> (message 	from Jan Kratochvil on Mon, 12 Oct 2009 18:14:24 +0200)
Subject: Re: Documentation generated from sources proposal
References:  <20091012161424.GA20603@host0.dyn.jankratochvil.net>
Mailing-List: contact gdb-help@sourceware.org; run by ezmlm
Precedence: bulk
List-Id: <gdb.sourceware.org>
List-Subscribe: <mailto:gdb-subscribe@sourceware.org>
List-Archive: <http://sourceware.org/ml/gdb/>
List-Post: <mailto:gdb@sourceware.org>
List-Help: <mailto:gdb-help@sourceware.org>, <http://sourceware.org/ml/#faqs>
Sender: gdb-owner@sourceware.org
X-SW-Source: 2009-10/txt/msg00385.txt.bz2

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