From: emery@ARIES.BERKELEY.EDU (David Emery)
Subject: documentation standards and browsers
Date: 19 Dec 88 22:02:24 GMT [thread overview]
Message-ID: <8812192202.AA00813@aries> (raw)
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)
reply other threads:[~1988-12-19 22:02 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
replies disabled
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox