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

[Sebastiaan Joosten]

I personally like it if the documentation of re-exported classes just
contain a summary, much like Data.Foldable does. The prelude documentation
is quite long already. I would not object to making the links stand out a
bit more though: a title 'More detailed descriptions' with a bulleted
summary to 'laws' might do that.
On where the laws need to be: I think for foldable the right decision is
made, there may be exceptions but I typically like to hear about the ideas
behind things before I dive into the algebraic characterization.

Also, many thanks to the write-up of Foldable.

Best,
Sebastiaan

On Thu, Sep 16, 2021 at 9:36 PM Chris Smith <cdsmith at gmail.com> wrote:

> Ah, I misunderstood you as well.  I agree that the laws should be included
> in the type class documentation.  In fact, most of the documentation from
> the link should probably be moved into the documentation for the class,
> rather than a stand-alone section.
>
> On Thu, Sep 16, 2021 at 9:15 PM David Feuer <david.feuer at gmail.com> wrote:
>
>> I'm not talking about whether they're first or last. They're currently
>> not part of the class documentation *at all*. They're only in the
>> Data.Traversable documentation.
>>
>> On Thu, Sep 16, 2021, 7:45 PM Viktor Dukhovni <ietf-dane at dukhovni.org>
>> wrote:
>>
>>> On Thu, Sep 16, 2021 at 06:51:42PM -0400, David Feuer wrote:
>>>
>>> > The last time I went to look at the laws it took me a couple minutes to
>>> > find them. I use them to write instances. Pretty important, IMO.
>>>
>>> I agree the laws are important to document, I just don't think they
>>> belong at the top of the module.  The beginner to intermediate users
>>> will be using the library and existing instances for some time before
>>> they start to write their own instances.
>>>
>>> If more modules adopt something like the style of the new Data.Foldable,
>>> experienced users will know to look for the laws at the end, if not
>>> still present at the top of the module.
>>>
>>> Of course perhaps the community would prefer the original Laws first
>>> format, I'm fine with that emerging as the consensus.  Perhaps worthy
>>> of a separate thread (made it so).
>>>
>>> Of course the conjectured users who might most benefit from not being
>>> intimidated by being exposed to laws before they're ready to understand
>>> them might not be present on this forum...
>>>
>>> --
>>>     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.
>>
>> _______________________________________________
>> 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.
>
> _______________________________________________
> 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/20210916/528c7734/attachment-0001.html>