For what it's worth, I agree with you both that it's important to document
the laws, and that it's not the most friendly way to begin the
documentation for a reader who is unfamiliar with the concept. It's not
clear to me whether the documentation ought to be optimized for readers who
are or aren't familiar with the concept, but I lean to the latter, which
means putting the type class laws at the end (but still easily accessible)
makes sense to me.
On Thu, Sep 16, 2021 at 7:47 PM Viktor Dukhovni
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.