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-Language: ENGLISH,ASCII-7-bit
X-Google-Thread: 103376,41cdd08c4c779b88
X-Google-Attributes: gid103376,public
X-Google-ArrivalTime: 2002-05-14 12:56:09 PST
Path: 
 archiver1.google.com!news1.google.com!newsfeed.stanford.edu!news-spur1.maxwell.syr.edu!news.maxwell.syr.edu!unlisys!news.snafu.de!news.eusc.inter.net!boavista!nobody
From: Michael Erdmann <Michael.Erdmann@snafu.de>
Newsgroups: comp.lang.ada
Subject: Re: Q: Generating Documenation from Ada Sources?
Date: Tue, 14 May 2002 20:01:49 +0200
Organization: [Posted via] Inter.net Germany GmbH
Message-ID: <3CE1510D.5030408@snafu.de>
References: <3CE02030.7040500@snafu.de>
 <i3XD8.875$ko7.73823340@newssvr14.news.prodigy.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit
X-Trace: news.eusc.inter.net 1021406168 14664 213.73.70.148 (14 May 2002
 19:56:08 GMT)
X-Complaints-To: abuse@eusc.inter.net
User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.0rc1) Gecko/20020417
X-Accept-Language: en-us, en
Xref: archiver1.google.com comp.lang.ada:24054
Date: 2002-05-14T20:01:49+02:00
List-Id: <comp.lang.ada>

tmoran@acm.org wrote:
>>>conventions in coding style, so AdaBrowse+ can know which comments are
>>>"relevant".
>>
>>...
>>currently playing around with certain heutistics based on a
>>minimal common sense snytax, e.g.
> 
> 
>   We went a different way, since most of the source files already
> existed, including customer's copies, and we didn't want to change
> them.  We have a database of information, for instance every entity
> has a Remarks section (which of course may be empty) and a Spec
> section.  Subprograms additionally have an Exceptions Raised section,
> and so forth.  These are filled in as much as possible by a program
> that scans source files for specs, links, comments saying "Raises ..."
> directly following a subprogram etc.  But this is viewed as just a
> convenience.  We expect most of the text to be entered, or at least
> modified by, a human writer.  Syntactic information like the file
> something is declared in, the package to "with" for it, any
> predefined constants of a type, etc comes from scanning the source
> code and is not modified by the documentation writer.
So you generated a templacte out of the source which might be
modified by the author.

May be this is one way to go. My Problem is that i like to make
it as easy as possible for an author to submit a package with
reasonable documentation. May be process could be like this:

Step 1 - Author presents package to the libary management
Step 2 - A tool is running over the software which generating a
          reasonable deocumentation skeleton.
Step 3 - Author updates the relevant sections
Step 4 - Final checkin, tooling checks  the contents of the
          documentation in the code and converts it to docbook!

Michael