From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14831 invoked by alias); 27 Jan 2004 19:31:43 -0000 Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org Received: (qmail 14772 invoked from network); 27 Jan 2004 19:31:41 -0000 Received: from unknown (HELO yosemite.airs.com) (209.128.65.135) by sources.redhat.com with SMTP; 27 Jan 2004 19:31:41 -0000 Received: (qmail 13866 invoked by uid 10); 27 Jan 2004 19:31:40 -0000 Received: (qmail 25497 invoked by uid 500); 27 Jan 2004 19:31:34 -0000 From: Ian Lance Taylor To: law@redhat.com Cc: kenner@vlsi1.ultra.nyu.edu (Richard Kenner), Joe.Buck@synopsys.com, gcc@gcc.gnu.org Subject: Re: "Documentation by paper" References: <200401271912.i0RJCN2J018928@speedy.slc.redhat.com> Date: Tue, 27 Jan 2004 19:43:00 -0000 In-Reply-To: <200401271912.i0RJCN2J018928@speedy.slc.redhat.com> Message-ID: User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.2 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-SW-Source: 2004-01/txt/msg02035.txt.bz2 law@redhat.com writes: > IMHO that's actually a huge long term liability as it actually discourages > writing good API interfaces and documenting them, while at the same time > encourages developers to actually look at the implementation to determine > if the code in question actually does what they want. I agree with you, but extracting documentation automatically from source code comments, and from the source code itself, isn't API documentation either. It's just another way of reading the source code. Source code and documentation aren't the same thing. The only case where I've seen source code work as documentation is Web (that is, the TeX implementation language), and Web is much harder to write than the combined effort of writing source code and separate documentation. The reason source code and documentation aren't the same thing is that they serve different purposes. Source code tells you what the function does. Documentation tells you how that fits into a larger plan. Documentation is organized for a human reader. Source code is organized for the compiler. The advantage of Web is that it lets you split apart a single function into different logical portions, and lets you group together the logical portions of several different functions. The most obvious use is that you can pull the error cases out of the function, leaving the reader looking only at the mainline case, which is generally much easier to understand and to document. Unfortunately, as noted, it's very hard to program this way. As I said, I'm not strongly opposed to extracting documentation from the gcc sources. But it's no substitute for actual documentation. Ian