documentation standards and browsers

documentation standards and browsers

[David Emery]

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)