[Haskell-cafe] Haskell reference documentation, laws first or laws last?
sjcjoosten+haskell at gmail.com
Fri Sep 17 02:13:27 UTC 2021
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.
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>
>>> 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...
>>> Haskell-Cafe mailing list
>>> To (un)subscribe, modify options or view archives go to:
>>> 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:
>> 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:
> Only members subscribed via the mailman list are allowed to post.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Haskell-Cafe