[Haskell-cafe] Haskell reference documentation, laws first or laws last?

[David Feuer]

I'll try to take a look. When writing instances (which I consider a
beginner-level activity), it's really important to learn to follow the
laws. While that may just sound like a bunch of theory, it turns out that
in practice violating typeclass laws leads to seriously unintuitive
behavior, breaking the expectations users have developed after using many
instances.

On Sat, Sep 18, 2021, 9:47 PM Viktor Dukhovni <ietf-dane at dukhovni.org>
wrote:

> On Thu, Sep 16, 2021 at 09:56:37PM -0400, Viktor Dukhovni wrote:
>
> > Surely a one click link from the Prelude re-export is no worse than a
> 1-click link
> > in the module table of contents?
> >
> > I am rather reluctant beat new readers over the head with laws that
> often are much
> > too abstract to add clarity.
>
> I've opened an MR:
> https://gitlab.haskell.org/ghc/ghc/-/merge_requests/6555
>
> that adds a "Laws" link to the class head haddocks, and attempts to
> improve some prose that was found a bit wanting in the recent threads.
>
>
> https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Prelude.html#g:11
>
>
> https://dnssec-stats.ant.isi.edu/~viktor/haskell/docs/libraries/base/Data-Foldable.html#overview
>
> The Overview of Data.Foldable is aimed at a novice to intermediate
> Haskell programmer, not a complete beginner or someone long familiar
> with the ins and outs of folds.  The idea is to help the reader be able
> to reason about the various Foldable methods and choose the right one
> for the task at hand.  Maybe, though not the main intent, to write better
> Foldable instances (if not simply derived).
>
> Perhaps the intended audience should be explicitly stated, to save
> complete beginners who are not ready for it, or seasoned Haskellers who
> don't need it the trouble of figuring out whether the content is for
> them???
>
> --
>         Viktor.
> _______________________________________________
> Haskell-Cafe mailing list
> To (un)subscribe, modify options or view archives go to:
> http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
> Only members subscribed via the mailman list are allowed to post.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20210918/c792a47a/attachment.html>