Mark partial functions as such

[Tikhon Jelvis]

This is a question of documentation, not type design. You don't have to
consider what exceptions your transitive dependencies might throw—you need
to understand what inputs *do* cause your function to fail. If you use head
in a safe way or have a call to error in an unreachable case, you shouldn't
say anything. On the other hand, if your function fails when the inputs
aren't relatively prime, you should document this regardless of whether the
failure is an exception you throw explicitly, a result of a partial pattern
match or a division by zero four layers of indirection away.

I definitely expect the author of a function to understand what inputs
cause that function to fail. If you don't understand this, you simply don't
understand the code you wrote. (Luckily, QuickCheck will probably find any
edge cases you missed when writing the function.)

Thinking about it a bit more, there's nothing specific to exceptions here.
If your code loops forever when the lengths of the inputs sum to a multiple
of seven, that's pretty handy to know from the documentation!

I would also expect the same style of documentation even for errors
expressed in the types with whatever your favorite generalization of Either
happens to be.

On Fri, Aug 31, 2018, 19:07 Bardur Arantsson <spam at scientician.net> wrote:

> On 31/08/2018 18.59, Oliver Charles wrote:
> > On Fri, Aug 31, 2018 at 5:21 PM Tikhon Jelvis <tikhon at jelv.is> wrote:
> >
> >> 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.
> >
> > Is this to be applied transitively? It has to be, to meet your
> > criteria, but this is a fairly unrealistic expectation to put on
> > library authors. If it's not applied transitively, then the
> > documentation creates a false sense of security - "catch these
> > exceptions that *I* throw and you're good!". I really think this part
> > of exceptions is a tooling problem that we have to solve. Haddock
> > should be responsible for figuring this out.
> >
>
> Not to mention the issues of "may throw" declarations for higher-order
> functions... (Java checked exceptions are basically broken[1] because of
> this. Well, this + the variance issues arising from inheritance and
> method signatures, but obviously Haskell doesn't have inheritance, so...)
>
> Regards,
>
> [1] They even break "catch" because everybody is forced to wrap
> "checked" exceptions in a RuntimeException if signatures don't specify
> "may throw anything", so you *also* have to check for wrapped exceptions
> in "catch" clauses. Anyway...
>
> _______________________________________________
> 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/cd6ae7fc/attachment-0001.html>