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=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Thread: 103376,81054609038e88e3 X-Google-Attributes: gid103376,public X-Google-Language: ENGLISH,ASCII Path: g2news1.google.com!news2.google.com!proxad.net!news.tele.dk!news.tele.dk!small.news.tele.dk!news-stoc.telia.net!telia.net!217.209.241.158.MISMATCH!newspeer1.se.telia.net!se.telia.net!masternews.telia.net.!newsc.telia.net.POSTED!not-for-mail From: =?ISO-8859-1?Q?Bj=F6rn_Persson?= User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.4.1) Gecko/20031114 X-Accept-Language: sv, sv-se, sv-fi, en-gb, en-us, en MIME-Version: 1.0 Newsgroups: comp.lang.ada Subject: Re: Literate Programming in Ada, AdaDoc, AdaBrowse References: <2sqmccF1oit5sU1@uni-berlin.de> <416b17ef$0$311$626a14ce@news.free.fr> In-Reply-To: <416b17ef$0$311$626a14ce@news.free.fr> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: quoted-printable Message-ID: Date: Tue, 12 Oct 2004 00:13:25 GMT NNTP-Posting-Host: 217.209.116.179 X-Complaints-To: abuse@telia.com X-Trace: newsc.telia.net 1097540005 217.209.116.179 (Tue, 12 Oct 2004 02:13:25 CEST) NNTP-Posting-Date: Tue, 12 Oct 2004 02:13:25 CEST Organization: Telia Internet Xref: g2news1.google.com comp.lang.ada:5061 Date: 2004-10-12T00:13:25+00:00 List-Id: Lionel Draghi wrote: > Stephen Leake wrote: >=20 >> Andre 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.=20 >=20 > This is just an absolutly perfect example of why the comments should no= t=20 > repeat what is already in the code :-) >=20 > On the other hand, if you have to comment about a special parameter=20 > semantics, parsing the whole Ada code won't help catching a discrepancy= =2E But at least it causes both "FTime" and "SysTime" to be carried over to=20 the document, making the discrepancy visible. If only "FTime" appeared=20 in the document, anyone trying to use the document would get strange=20 compilation errors, and only when in desperation they resorted to=20 reading the code would the reason be revealed. --=20 Bj=F6rn Persson PGP key A88682FD omb jor ers @sv ge. r o.b n.p son eri nu