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@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@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries