[m-rev.] for review: Clarify meaning of "abort" in library documentation.

[Peter Wang]

On Sun, 8 Oct 2017 05:56:38 -0400 (EDT), Julien Fischer <jfischer at opturion.com> wrote:
> 
> Hi Peter,
> 
> On Sun, 8 Oct 2017, Peter Wang wrote:
> 
> > library/assoc_list.m:
> > library/bag.m:
> > library/bimap.m:
> > library/calendar.m:
> > library/char.m:
> > library/digraph.m:
> > library/list.m:
> > library/map.m:
> > library/multi_map.m:
> > library/psqueue.m:
> > library/rbtree.m:
> > library/string.m:
> > library/term.m:
> > library/tree234.m:
> > library/type_desc.m:
> > library/univ.m:
> > library/varset.m:
> >    Replace most occurrences of "abort" with "throw an exception".
> 
> I think it would be even better if the messages said what kind
> of exception is thrown.

We would need to commit to the types thrown by each predicate or
function, and I'm not sure 'software_error' is the best we can do.

> 
> It would also be good to extend to the library documentation section of
> the coding standards to describe how exceptions thrown by library
> predicates should be documented.

See below.

> 
> > diff --git a/library/assoc_list.m b/library/assoc_list.m
> > index a3c04fa96..6a65c2569 100644
> > --- a/library/assoc_list.m
> > +++ b/library/assoc_list.m
> > @@ -33,7 +33,8 @@
> > :- func reverse_members(assoc_list(K, V)) = assoc_list(V, K).
> > :- pred reverse_members(assoc_list(K, V)::in, assoc_list(V, K)::out) is det.
> > 
> > -    % Zip together two lists; abort if they are of different lengths.
> > +    % Zip together two lists.
> > +    % Throw an exception if they are of different lengths.
> 
> s/Throw/Throws/ here and below.

You mean you want "throws" in all cases? I kept the documentation
prescriptive or descriptive as it was.

Peter


diff --git a/compiler/notes/coding_standards.html b/compiler/notes/coding_standards.html
index 89e5b77a2..e2e507ad6 100644
--- a/compiler/notes/coding_standards.html
+++ b/compiler/notes/coding_standards.html
@@ -550,6 +550,13 @@ want to maintain a uniform appearance as much as is possible.
 Avoid module qualification in the interface sections of library modules except
 where necessary to resolve ambiguity.
 
+<p>
+
+A predicate or function which throws exceptions under certain conditions
+should be described as such, using the phrase "throws an exception".
+A predicate or function that may cause a runtime abort should be described
+as such, using the phrase "runtime abort".
+
 <h2> Testing </h2>
 
 <p>