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

[Julien Fischer]

Hi Peter,

On Mon, 9 Oct 2017, Peter Wang wrote:

> 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 isn't the best we can do, however (in most cases) it *is* what's
done.  (I think for the cases where we throw exceptions of a different
type then we already document that.)

>> 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.

Looks fine.

>>> 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.

Fair enough.

Julien.