[m-dev.] for discussion: coding standards and the library reference manual

[Julien Fischer]

The diff below outlines a change to the coding standards
that would standardize the documentation of predicates in
the standard library (and with it the appearance of library reference
manual).

At the moment there are a wide variety of documentation styles
in the library - in the interests of clarity I suggest that
we should choose one style and stick to it (at least for things
that will end up in the library reference manual).

Since the most common style seems to be to place the
description of a predicate above the :- pred declaration,
that's what is below.

Opinions?

Julien.

Index: coding_standards.html
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/notes/coding_standards.html,v
retrieving revision 1.12
diff -u -r1.12 coding_standards.html
--- coding_standards.html	12 Jan 2004 12:06:31 -0000	1.12
+++ coding_standards.html	23 Mar 2004 05:59:34 -0000
@@ -362,6 +362,51 @@
 Note that these dividing lines should not exceed the 79 character limit
 (see above).

+<h2> Standard Library Predicates </h2>
+
+Any predicate or function that occurs in the interface of a standard
+library module must have a brief comment describing what it does.
+Ideally this description should note any conditions under which the
+predicate can fail or throw an exception.
+
+The comment must be positioned directly above the predicate, as follows:
+
+<pre>
+
+		% Description of predicate foo.
+	:- pred foo(...
+	:- mode foo(...
+	:- mode foo(...
+</pre>
+
+In some cases it may be clearer to place a blank comment between the
+description and the predicate/function declaration, as follows:
+
+<pre>
+
+		% Description of predicate foo.
+		%
+	:- pred foo(...
+	:- mode foo(...
+</pre>
+
+
+A group of related predicate, mode and function declarations may be grouped
+together under a single description provided that it is formatted as above.
+
+<pre>
+
+		% Insert a new key and corresponding value into a map.
+		% Fail if the key already exists.
+	:- pred map.insert(map(K, V)::in, K::in, V::in, map(K, V)::out) is det.
+	:- func map.insert(map(K, V), K, V) = map(K, V).
+
+</pre>
+
+The reason for using this particular style is that the reference manual for
+the standard library is automatically generated from the module interfaces
+and we want, as much as is possible, to maintain an uniform appearance.
+
 <h2> Testing </h2>

 <p>

--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------