[m-rev.] for review: Clarify meaning of "abort" in library documentation.
novalazy at gmail.com
Mon Oct 9 09:11:50 AEDT 2017
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.
> > 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.
diff --git a/compiler/notes/coding_standards.html b/compiler/notes/coding_standards.html
index 89e5b77a2..e2e507ad6 100644
@@ -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.
+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>
More information about the reviews