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