On Thu, Sep 16, 2021 at 04:57:28PM -0400, David Feuer wrote:
I am not a fan of how the new Traversable documentation buries the actual laws.
The laws are one click away from the table of contents, and IMHO not particularly illuminating other than for advanced readers. For example, in Data.Foldable they are: foldr f z t = appEndo (foldMap (Endo . f) t ) z foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z fold = foldMap id length = getSum . foldMap (Sum . const 1) is someone new to Data.Foldable really going to learn something from these before they've deeply understood the background concepts? My take is that the laws should almost always be "buried" (one click away) at the end of the module documentation. Those who care and need them can find them, but I think they just intimidate the less experienced readers. Putting the laws first likely only discourages beginners. -- Viktor.