From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22148 invoked by alias); 1 Feb 2004 12:17:51 -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 22100 invoked from network); 1 Feb 2004 12:17:50 -0000 Received: from unknown (HELO vlsi1.ultra.nyu.edu) (128.122.140.213) by sources.redhat.com with SMTP; 1 Feb 2004 12:17:50 -0000 Received: by vlsi1.ultra.nyu.edu (4.1/1.34) id AA03953; Sun, 1 Feb 04 07:20:18 EST Date: Sun, 01 Feb 2004 12:17:00 -0000 From: kenner@vlsi1.ultra.nyu.edu (Richard Kenner) Message-Id: <10402011220.AA03953@vlsi1.ultra.nyu.edu> To: asutton@cs.kent.edu Subject: Re: "Documentation by paper" Cc: gcc@gcc.gnu.org X-SW-Source: 2004-02/txt/msg00039.txt.bz2 maybe it's me, but it seems a bit odd that people would argue against documentation extraction in favor of having developers look at the implementation as a reference. but then again, i'm only a software engin... i mean grad student. I haven't heard anybody make that argument. The issue is that of "extraction". A lot of us fail to see that "extracting" documentation is useful and if the method of generating it involves anotations that make the source harder to read and write, it's a net negative. As Robert points out, if you generate a separate file for documentation, it's easy to have old versions of that file around without knowing it. If all the documentation (both specification and implementation) is in the same place as the source, you don't have that risk.