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=-0.8 required=5.0 tests=BAYES_00,INVALID_DATE
	autolearn=no autolearn_force=no version=3.4.4
Path: utzoo!utgpu!watmath!clyde!att!osu-cis!tut.cis.ohio-state.edu!rutgers!ucsd!ucbvax!ARIES.BERKELEY.EDU!emery
From: emery@ARIES.BERKELEY.EDU (David Emery)
Newsgroups: comp.lang.ada
Subject: documentation standards and browsers
Message-ID: <8812192202.AA00813@aries>
Date: 19 Dec 88 22:02:24 GMT
Sender: daemon@ucbvax.BERKELEY.EDU
Organization: The Internet
List-Id: <comp.lang.ada>

I would like to hear from anyone who has developed an on-line Ada
browser (either standalone, or part of another tool, such as Emacs).
In particular, what I am interested in is how your browser expects to
find comments associated with an Ada declaration.  For instance,
assume that you ask the browser to find the declaration for
SOME_ADA_PACKAGE.A_PROCEDURE.  Here's one possible 'comment block' for
a procedure (note I don't say this is a good way to document a
procedure...):
	
	procedure A_PROCEDURE 
			(param1 : T1;
				-- comment on param1
			 param2 : T2
				-- comment on param2
			);
	  -- Purpose:  A_PROCEDURE does so and so...
	  -- Pre-Conditions:  param1 must be munged before calling 
	  --                  A_PROCEDURE...
	  -- Post-Conditions:  the state of SOME_ADA_PACKAGE is now whatever...
	  -- EXCEPTIONS:  
	  -- NOT_MUNGED is raised if param1 was not munged before A_PROCEDURE
	  --	was called...
	  -- CONSTRAINT_ERROR may be raised for whatever reason...

The idea is that when you ask the browser to show you A_PROCEDURE, you
get both the Ada declaration and all associated comments.  In this
case, my hypothetical browser expects all comments to follow the
procedure declaration.  No blank lines are permitted/expected between
the procedure declaration and the end of the associated comments.  The
browser can make use of the 'Reserved comment words' "Purpose,
Pre-Conditions, Post-Conditions, and Exceptions" in some manner.

Thanks, I'll summarize (unless you ask me not to...)

				dave emery
				emery@mitre.org (new style address)
				emery@mitre-bedford.arpa (old style address)
				linus!dee (uucp)