Mark partial functions as such

[Tikhon Jelvis]

Deeper questions of partiality aside, if a function can throw exceptions,
the documentation should spell this out *explicitly*, ideally also
specifying what the type of the exception may be. To me, this is a
*minimum* standard to expect from documentation in any language with
exceptions.

Whenever I write a function that might error out in my work code, I always
write a separate paragraph explaining this. Usually it reads something like
"Raises an error if these conditions aren't met" for whatever preconditions
the function has. I don't know if this documentation requirement is in our
style guide, but if it isn't I should put it in :).

This is definitely something we should have in the documentation for base.
I would document head something like this:

> Return the first element of the given list.

> Raises an 'ErrorCall' exception if the list is empty.

I could see a case for putting less emphasis on the fact that it's a
specific exception—exceptions in pure functions are a bit weird—but the
basic structure would still be the same: a distinct part of the
documentation calling out the error condition explicitly.


On Fri, Aug 31, 2018, 17:54 Henning Thielemann <
lemming at henning-thielemann.de> wrote:

>
> On Fri, 31 Aug 2018, Ryan Trinkle wrote:
>
> > This is probably not really for the libraries list, but in the same vein
> > as this discussion, I think it would be extremely helpful to have a way
> > of banning functions that does *not* require changing the upstream
> > library.  I would be thrilled to have a machine-checked ban on use of
> > the 'head', 'tail', etc.
>
> So far I have HLint rules to ban them. Unfortunately, they do not work
> transitively. People have already proposed a TotalHaskell pragma
> analogously to SafeHaskell._______________________________________________
> Libraries mailing list
> Libraries at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/libraries/attachments/20180831/332a35c2/attachment.html>