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

Fri Jan 4 00:49:26 UTC 2019

I'm sympathetic to the notion that instances are an important part of the
API.  On the other hand, it's hard to argue against how much more usable
the documentation becomes when all the page-long instance lists are
collapsed.  I wonder if there's a compromise possible: in the collapsed
form, the instance list could still show a list of the applicable class
names, but all on one line instead of a page-long table.  Then it's just a
click away to get from there to the details (instance context, source link,
etc.) that are shown now.

On Thu, Jan 3, 2019 at 7:31 PM George Wilson <george at wils.online> wrote:

> Type class instances are an essential part of a data type's API in
> Haskell so I'm against hiding them by default. A toggle to collapse
> all instance blocks on a page would be fine.
>
> Cheers,
> George
>
> On Fri, 4 Jan 2019 at 04:36, Nathan Collins <nathan.collins at gmail.com>
> wrote:
> >
> > * I think collapsing instances by default is a great idea! +1
> >
> > * Examples are already collapsed by default, and I think instances
> > should be treated the same way.
> >
> > Re the concern that this would make the Servant docs worse, for me it
> > would just be a matter of knowing to expand the instance docs when I'm
> > interested in the corresponding class, the same way I expand the
> > examples only where I'm interested.
> >
> > Here's an example of instance docs in Servant:
> >
> http://hackage.haskell.org/package/servant-0.15/docs/Servant-API.html#t:FromHttpApiData
> .
> > Until I'm interested in the FromHttpApiData class, I don't personally
> > want to see that long list of instances with some examples. Also, in
> > my experience, having lots of docs/examples on the instances like this
> > is not very common.
> >
> > Here's an instance of examples being collapsed by default to good
> > effect in the Prelude docs for Either:
> >
> https://hackage.haskell.org/package/base-4.12.0.0/docs/Prelude.html#t:Either
> >
> > * Having a "collapse all/expand all" toggle at the top of the page
> > would be nice, but if the default is not "collapsed" then I'd want a
> > way to make that my personal default.
> >
> > I don't know much about web development, but my impression is that we
> > could use a cookie and some simple JavaScript [1] to make "collapse by
> > default" a per-user preference, say by remembering the last state of
> > the hypothetical "collapse all/expand all" toggle button at the top.
> > Haddock already uses JavaScript, so I expect this would be a small
> > addition.
> >
> > Cheers,
> >
> > -nathan
> >
> > [1] https://developer.mozilla.org/en-US/docs/Web/API/document/cookie
> >
> > On Wed, Jan 2, 2019 at 11:23 PM Oleg Grenrus <oleg.grenrus at iki.fi>
> wrote:
> > >
> > > How about a compromise: show dozen or so instances with "show rest"
> link-toggle. That would work very nicely, if we could control which
> instances (e.g. instances with haddocks) should be shown.
> > >
> > > E.g. in `servant` *a lot* of docs & examples are in instance haddocks,
> so making them hidden will make documentation strictly worse.
> > >
> > > - Oleg
> > >
> > > On 3 Jan 2019, at 7.50, Ryan Reich <ryan.reich at gmail.com> wrote:
> > >
> > > 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.
> > >
> > > _______________________________________________
> > > 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.
> _______________________________________________
> 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/20190103/ddbccd75/attachment.html>