@partial metadata for partial/non-total function with a pure type signature

[Kleidukos]

Hello maintainers and contributors,

Following this merge request in base's documentation, and an interesting comment from Ben Gamari, I lay before you the possibility of having an additional metadata annotation:

@partial <optional message>

to indicate the fact that a function with a seemingly innocent type signature (such as maximum :: (Foldable t, Ord a) => t a -> a) might in fact raise a runtime exception.

There are of course some other things to sort out, notably at the UI/UX level.
Does haskell.org or any of the corporate sponsors have any people with this skillset that could be of any help?

I hope this will lead to some interesting advances in how we document our Haskell code. :)

cc @bgamari @cartazio

[bgamari]

The only thing that makes me nervous here is that it's somewhat of a lie. A function lacking @partial may very well diverge, even if its RHS appears to be total. Afterall, the function may use a function that is itself non-total.

[Kleidukos]

@bgamari This is indeed a valid concern. My opinion would be to be honest regarding the limitations of this metadata, with maybe some kind of tooltip on the metadata, that would explain that this does not equate a formal proof of totality and is user-defined (or something like that).

[cartazio]

I think it might be better to flip it around : rather than just saying it’s partial, it should be a “has failure modes”. Eg length and most other recursive / finite length assuming algorithms will fail in the sense of an infinite loop on a cyclic list ! May throw exception is one annotation May nonterminate on certain lazy / infinite structures is another. Maybe step zero is we start a document that tracks all the safety properties different functions in base require (what conditions for infinite loop, throwing an exception based on inputs/state etc). Then figure out what we may want from a documentation and or tooling support. I worry that unless we first write down all these and look at it holistically, we may miss an opportunity to do something cool with the whole big picture.

…

On Sun, Mar 22, 2020 at 5:24 AM Hécate ***@***.***> wrote: @bgamari <https://github.com/bgamari> This is indeed a valid concern. My opinion would be to be honest regarding the limitations of this metadata, with maybe some kind of tooltip on the metadata, that would explain that this does not equate a formal proof of totality and is user-defined (or something like that). — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1139 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAABBQTVRFQU54VMKMJ5J2DRIXKLXANCNFSM4LQ4AKFA> .

[Kleidukos]

Thank you Carter for the insight!

On my side, I suggest we first go with marking functions for which a (direct) code path to undefined/error/errorWithoutStacktrace/throw is possible.
This excludes functions calling such functions because we wouldn't see the end of it, but it can be a good start if we want to lead to way to a glorious future where we have a proper termination checker in GHC.
And better docs. That's why we're here. ;)

[TixieSalander]

Hello, @Kleidukos asked me to work on the annotation's UI integration. I'll take look on how I can help.

[Kleidukos]

Tixie is a wonderful designer and I have had the chance of working with her in the past.
I am sure she will be able to fill some gap in our skill set. :)

[Kleidukos]

For reference, here is an example of a function that is partial (with its current warning), and has an example section:

[cartazio]

i'd really like it to be collapsable :)

[cartazio]

so

Warning Sigil Partiality: then the collapsed info which explain , or something along those lines, we can compare several flavors and figure it out

[cartazio]

restating part of a discussion on irc, i was suggesting "@partiality", or something like that, be the grammatical analogue of

[TixieSalander]

Here the result of a first iteration designing warning message in the documentation:

• I emphasized the message with a light colored box + an icon
• I've choose a standard color for a warning message but in pastel shades to harmonize nicely
• High contrast between text and background (WCAG AAA compliant)

[chessai]

note that there is a typo in that image, should be 'Exception', not 'Excepetion'.

Additionally, I think 'has failure modes' is a step in the right direction.

[cartazio]

i do think the WARNING SIGIL Partiality piece should then have the text under it
a la examples toggle

[Kleidukos]

@cartazio So something like

⚠️ Partiality

This function is partial and may raise a runtime exception…

[cartazio]

Yes!
With the body being the documentation about side conditions for failure / correctness and or examples thereof