[m-rev.] for review: Clarify meaning of "abort" in library documentation.
jfischer at opturion.com
Mon Oct 9 10:19:16 AEDT 2017
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:
>>> 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.
>>> 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.
More information about the reviews