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

Fri Jan 4 00:45:46 UTC 2019

They're essential, but they're also at minimum an impediment to navigation
and to some extent comprehension of a haddock. Arguably what we really need
is a better way to present them, but until then collapsed by default is
reasonable.

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.

-- 
brandon s allbery kf8nh
allbery.b at gmail.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20190103/41fb577c/attachment.html>