<div dir="auto">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.<div dir="auto"><br></div><div dir="auto">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 :).</div><div dir="auto"><br></div><div dir="auto">This is definitely something we should have in the documentation for base. I would document head something like this:</div><div dir="auto"><br></div><div dir="auto">> Return the first element of the given list.</div><div dir="auto"><br></div><div dir="auto">> Raises an 'ErrorCall' exception if the list is empty.</div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div></div><br><div class="gmail_quote"><div dir="ltr">On Fri, Aug 31, 2018, 17:54 Henning Thielemann <<a href="mailto:lemming@henning-thielemann.de">lemming@henning-thielemann.de</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><br>
On Fri, 31 Aug 2018, Ryan Trinkle wrote:<br>
<br>
> This is probably not really for the libraries list, but in the same vein <br>
> as this discussion, I think it would be extremely helpful to have a way <br>
> of banning functions that does *not* require changing the upstream <br>
> library.  I would be thrilled to have a machine-checked ban on use of <br>
> the 'head', 'tail', etc.<br>
<br>
So far I have HLint rules to ban them. Unfortunately, they do not work <br>
transitively. People have already proposed a TotalHaskell pragma <br>
analogously to SafeHaskell._______________________________________________<br>
Libraries mailing list<br>
<a href="mailto:Libraries@haskell.org" target="_blank" rel="noreferrer">Libraries@haskell.org</a><br>
<a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries" rel="noreferrer noreferrer" target="_blank">http://mail.haskell.org/cgi-bin/mailman/listinfo/libraries</a><br>
</blockquote></div>