[Haskell-cafe] RFC: in haddock, collapse instances by default

Ryan Reich ryan.reich at gmail.com
Thu Jan 3 05:50:32 UTC 2019


I think this is a great idea.  I do wonder, however, if it might exacerbate
a kind of meta-documentation problem that I, at least, had when I was more
of a beginner: it was not clear to me that most of a type's API is implicit
in its instances of many standard classes, and specialized functions for
things like mapping or folding or appending may not even be present in the
rest of the module.  Obviously this is something that every Haskeller needs
to learn, but it was an issue for me even when the instance lists were
present for me to gloss over.

Perhaps Haddock could, rather than establishing this as a new default,
provide a "collapse all" and "expand all" set of functions at the top of
the page?

On Wed, Jan 2, 2019 at 8:03 PM Li-yao Xia <lysxia at gmail.com> wrote:

> Hello Café,
>
> I would like to propose making haddock keep instance lists collapsed by
> default. Some discussion is in order since it would significantly affect
> the documentation of many packages on Hackage.
>
> Feel free to reply here or on the related Github thread:
> https://github.com/haskell/haddock/issues/698
>
> 1. Instance lists take a lot of screen estate
>
> For a motivating example, I can point to the Prelude we all love.
>
> https://hackage.haskell.org/package/base-4.12.0.0/docs/Prelude.html
>
> We are immediately welcomed by half a page of instances of Bool, which
> is not quite bad, but classes have the most impressive instance lists,
> as you may see when you reach Eq.
>
> Many packages, even commonly used ones, have the same issue. For an
> extreme example, see the scrollbar jump when you fold the instance list
> of Apply in singletons.
>
>
> https://hackage.haskell.org/package/singletons-2.5.1/docs/Data-Singletons.html#t:Apply
>
> 2. Current workarounds
>
> They can be collapsed manually one by one, and we can jump to the middle
> of a module with the table of contents, but scrolling up from the bottom
> of an instance list is still a chore.
>
> Of course, instance lists also contain quite important information.
> Would it become too easy to miss if it were hidden by default? Would a
> more fine-grained alternative be better?
>
> Regards,
> Li-yao
> _______________________________________________
> 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/20190102/1d0c724e/attachment.html>


More information about the Haskell-Cafe mailing list