From mboxrd@z Thu Jan  1 00:00:00 1970
X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me
X-Spam-Level: 
X-Spam-Status: No, score=-2.9 required=5.0 tests=BAYES_00,MAILING_LIST_MULTI
	autolearn=unavailable autolearn_force=no version=3.4.4
X-Google-Thread: 103376,81054609038e88e3
X-Google-Attributes: gid103376,public
X-Google-Language: ENGLISH,ASCII-7-bit
Path: 
 g2news1.google.com!news2.google.com!proxad.net!freenix!enst.fr!melchior!cuivre.fr.eu.org!melchior.frmug.org!not-for-mail
From: Stephen Leake <stephen_leake@acm.org>
Newsgroups: comp.lang.ada
Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse
Date: 10 Oct 2004 11:24:46 -0400
Organization: Cuivre, Argent, Or
Message-ID: <mailman.260.1097423011.390.comp.lang.ada@ada-france.org>
References: <2sqmccF1oit5sU1@uni-berlin.de>
	<ckavmo$2v3$1@news6.zwoll1.ov.home.nl>
NNTP-Posting-Host: lovelace.ada-france.org
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Trace: melchior.cuivre.fr.eu.org 1097423012 265 212.85.156.195 (10 Oct 2004
 15:43:32 GMT)
X-Complaints-To: usenet@melchior.cuivre.fr.eu.org
NNTP-Posting-Date: Sun, 10 Oct 2004 15:43:32 +0000 (UTC)
To: comp.lang.ada@ada-france.org
Return-Path: <stephen_leake@acm.org>
In-Reply-To: <ckavmo$2v3$1@news6.zwoll1.ov.home.nl>
User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3
X-Virus-Scanned: by amavisd-new-20030616-p10 (Debian) at ada-france.org
X-BeenThere: comp.lang.ada@ada-france.org
X-Mailman-Version: 2.1.4
Precedence: list
List-Id: "Gateway to the comp.lang.ada Usenet newsgroup"
	<comp.lang.ada.ada-france.org>
List-Unsubscribe: <http://www.ada-france.org/mailman/listinfo/comp.lang.ada>,
	<mailto:comp.lang.ada-request@ada-france.org?subject=unsubscribe>
List-Post: <mailto:comp.lang.ada@ada-france.org>
List-Help: <mailto:comp.lang.ada-request@ada-france.org?subject=help>
List-Subscribe: <http://www.ada-france.org/mailman/listinfo/comp.lang.ada>,
	<mailto:comp.lang.ada-request@ada-france.org?subject=subscribe>
Xref: g2news1.google.com comp.lang.ada:4998
Date: 2004-10-10T11:24:46-04:00

Andre <avsaway@hotmail.com> writes:

> I think you need to keep it simple (as many of the replies also state)
> Here a sample of how I write down my comment in the source code.
> 
>     --  .Operation: Put a date-time in a string
>     --  .Preconditions:
>     --   .in: FTime, the date-time
>     --  .Semantics:
>     --   Format the date-time in yyyy-mm-dd hh:mm:ss.mmm
>     --  .Postconditions:
>     --   .return: a string with the date-time
>     function Date_As_Str
>        (SysTime : SYSTEMTIME)
>        return String;

This is an absolutly perfect example of why the documentation
generator needs to parse the full Ada code. What is the name of the
parameter? The document says "FTime", the code says "SysTime". 

I don't trust _anyone_ to maintain comments like this. That's what
tools are for!

-- 
-- Stephe