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

Fri Jan 4 10:26:57 UTC 2019

I like Chris' idea about inline list by default, with the ability to a) get
the whole list in old format, b) hide the stuff completely.

--
Best, Artem

On Fri, 4 Jan 2019 at 03:50 Chris Smith <cdsmith at gmail.com> wrote:

> 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.
>
> _______________________________________________
> 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/20190104/16d4968d/attachment-0001.html>