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,887292c91e10d3fd
X-Google-NewGroupId: yes
X-Google-Attributes: gida07f3367d7,domainid0,public,usenet
X-Google-Language: ENGLISH,ASCII-7-bit
Path: 
 g2news2.google.com!news4.google.com!feeder.news-service.com!feeder.ecngs.de!ecngs!feeder2.ecngs.de!194.25.134.126.MISMATCH!newsfeed01.sul.t-online.de!t-online.de!newsfeed.arcor.de!newsspool2.arcor-online.net!news.arcor.de.POSTED!not-for-mail
Date: Mon, 15 Nov 2010 15:56:31 +0100
From: Georg Bauhaus <rm.dash-bauhaus@futureapps.de>
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US;
 rv:1.9.2.12) Gecko/20101027 Thunderbird/3.1.6
MIME-Version: 1.0
Newsgroups: comp.lang.ada
Subject: Re: Ada documentation tools.
References: <s5adnQTW9suR_33RRVn_vwA@giganews.com>
 <c2c16ca4-9833-4947-a549-6de773ef78dc@35g2000prb.googlegroups.com>
 <6f234690-e21d-4d78-8dba-c017976029e9@z17g2000prz.googlegroups.com>
 <80dacf60-a610-4004-9298-69751bbfcaea@j12g2000prm.googlegroups.com>
 <8cdfee44-a675-46a3-b850-77661400dbc8@j9g2000vbr.googlegroups.com>
 <1c9aff07-3b32-4492-bd33-7f826bd47e10@f16g2000prj.googlegroups.com>
In-Reply-To: 
 <1c9aff07-3b32-4492-bd33-7f826bd47e10@f16g2000prj.googlegroups.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Message-ID: <4ce14a1f$0$7667$9b4e6d93@newsspool1.arcor-online.net>
Organization: Arcor
NNTP-Posting-Date: 15 Nov 2010 15:56:31 CET
NNTP-Posting-Host: 295fd576.newsspool1.arcor-online.net
X-Trace: 
 DXC=Vb>7me2HlYlfF8a^:6>b7eic==]BZ:afn4Fo<]lROoRa<`=YMgDjhgb^ho\<72OWSonc\616M64>jLh>_cHTX3jmYk[Bihf=9ff
X-Complaints-To: usenet-abuse@arcor.de
Xref: g2news2.google.com comp.lang.ada:16480
Date: 2010-11-15T15:56:31+01:00
List-Id: <comp.lang.ada>

On 15.11.10 15:25, AdaMagica wrote:

> The original wish was to have something like JavaDoc for Ada, which
> just extracts the comments and strips the implementation to produce
> something similar to what the Ada spec is per se.
> 
> Colouring, fonts etc. are rather more than just JavaDoc (modern
> language sensitive IDEs have all this). OK, I haven't used Java for
> years, so perhaps JavaDoc today is more than then.

JavaDoc does more than to extract, literally.  JavaDoc is a small
tagging language.  The tags introduce references to items internal
and external to the Java source.  Internal references are checked.

Then, stale comments, referring to parameters that do no longer
exist are not possible. For example, when using the  @param tag
in the method comment.

Python, similarly, has a mechanism for associating comments
and definitions: documentation strings. These comments are
run-time entities, available to any program in the __doc__
attribute of any objects (this includes functions and classes
which are objects, too).

<Example>

Python>>> print str.__doc__
str(object) -> string

Return a nice string representation of the object.
If the argument is a string, the return value is the same object.
Python>>>

</Example>

Python users have established an informal convention about
identifier names in comments. Ada users haven't, have they?

The informal convention is to place identifier names between
`backticks` when the word refers to named variables of that name.

- Python has full introspective capabilities ...

- Algol 60 (!) has the "comment" key word.

- Eiffel has an "indexing" section at the start of each class.

The Ada language---it keeps being associated with software
engineering---must, to support this association, have supporting
tools that address proper comments.  And do it formally,
otherwise documentation is necessarily bricolage.