From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17901 invoked by alias); 21 Dec 2007 04:36:25 -0000 Received: (qmail 17890 invoked by uid 22791); 21 Dec 2007 04:36:24 -0000 X-Spam-Check-By: sourceware.org Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.31) with ESMTP; Fri, 21 Dec 2007 04:36:19 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 64C872A9681; Thu, 20 Dec 2007 23:36:17 -0500 (EST) Received: from rock.gnat.com ([127.0.0.1]) by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 95F8MdJG6BeI; Thu, 20 Dec 2007 23:36:17 -0500 (EST) Received: from joel.gnat.com (localhost.localdomain [127.0.0.1]) by rock.gnat.com (Postfix) with ESMTP id 8B1302A9653; Thu, 20 Dec 2007 23:36:16 -0500 (EST) Received: by joel.gnat.com (Postfix, from userid 1000) id 5E3E2E7ACA; Fri, 21 Dec 2007 08:36:08 +0400 (RET) Date: Fri, 21 Dec 2007 05:02:00 -0000 From: Joel Brobecker To: Eli Zaretskii Cc: uweigand@de.ibm.com, gdb-patches@sourceware.org Subject: Re: [RFC/RFA] Introduce new struct parse_context Message-ID: <20071221043608.GJ6154@adacore.com> References: <20071217064213.GC9022@adacore.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.4.2.2i Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2007-12/txt/msg00359.txt.bz2 Eli, > How about if we try to document in gdbint.texinfo each new > infrastructure we introduce, from now on? Would other maintainers > support such a requirement from contributors? I can offer > text-to-Texinfo conversion services (and, of course, general help in > writing documentation), if someone does not feel up to speed with > Texinfo. Generally speaking, I am very committed to good documentation. I would tend to say that your suggestion is a good one, and we should request documentation when necessary. But I think that this should be evaluated on a case-by-case basis, because there are some times when external documents such as gdbint will be more useful, and other times when it will be more appropriate to leave the documentation as a comment embedded in the code. Let's take the two patches of this thread as an example. Would you suggest to move the documentation to gdbint, or leave it in the code? To me, it seems better to put keep the documentation with the code. If we were to put some documentation in gdbint for this patch, what would you put? -- Joel