RFC: in haddock, collapse instances by default

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

RFC: in haddock, collapse instances by default

Li-yao Xia-2
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.
Reply | Threaded
Open this post in threaded view
|

Re: RFC: in haddock, collapse instances by default

Ian Denhardt
Quoting Li-yao Xia (2019-01-02 11:18:41)

> 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

Another example where this gets a little ridiculous is my capnp package,
which defines a few type classes with instances for most types in the
generated code, e.g:

https://hackage.haskell.org/package/capnp-0.3.0.0/docs/Data-Capnp-Classes.html

It's not quite as absurd as the singletons package, but from eyeballing
the size of my scrollbar I'd guess that the instance lists are 80-90% of
that page.

> 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?

Personally I rarely use them.

It was mentioned on the Github issue/pr as well, but I think a
collapse/expand all would be a good idea. My personal inclination would
be to have it collapsed by default, though I feel less strongly about
this.

-Ian
_______________________________________________
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.
Reply | Threaded
Open this post in threaded view
|

Re: RFC: in haddock, collapse instances by default

Ryan Reich
In reply to this post by Li-yao Xia-2
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 <[hidden email]> 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.
Reply | Threaded
Open this post in threaded view
|

Re: RFC: in haddock, collapse instances by default

Oleg Grenrus
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 <[hidden email]> 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 <[hidden email]> 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.
Reply | Threaded
Open this post in threaded view
|

Re: RFC: in haddock, collapse instances by default

Nathan Collins
* 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
Reply | Threaded
Open this post in threaded view
|

Re: RFC: in haddock, collapse instances by default

George Wilson
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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
Reply | Threaded
Open this post in threaded view
|

Re: RFC: in haddock, collapse instances by default

Brandon Allbery
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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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

_______________________________________________
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.
Reply | Threaded
Open this post in threaded view
|

Re: RFC: in haddock, collapse instances by default

Chris Smith-31
In reply to this post by George Wilson
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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.
Reply | Threaded
Open this post in threaded view
|

Re: RFC: in haddock, collapse instances by default

Artem Pelenitsyn
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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.

_______________________________________________
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.
Reply | Threaded
Open this post in threaded view
|

Re: RFC: in haddock, collapse instances by default

Li-yao Xia-2
Thanks everyone for the response! To summarize the discussion:

- There is general agreement that the current default can be
problematic, but switching it the other way around doesn't seem
unequivocally good either.

To add to that counterpoint, I must admit that mtl and time are examples
where the instance lists are arguably quite essential to understand
those libraries, and for familiar users they aren't that uncomfortably long.

In that case, a safer solution seems to keep the current default to not
surprise users that are already happy with the current state of things,
but add a new option to change the default, to address the cases where
they are indeed a problem.

- A button to fold/unfold all instance lists seems like an unanimously
good idea.

     * Perhaps the same feature for collapsible examples would be
similarly useful.

     * We can record users preferences. In fact, it appears Haddock
already records which instance lists are folded.

I am currently interested in implementing the features mentioned above.

- There were also suggestions to make the presentation of instance lists
more compact, rather than entirely hide them. I am in favor of them, but
of course that is more work to flesh out and implement.

     * Show only some instances (for example, those that have comments
attached).

     * List the relevant classes/types on a single line (rather than the
whole instance heads, that are somewhat redundant), with the option to
switch to the current display for more details.

It seems reasonable to leave these as future tasks, and interested
parties are free to discuss and take them on any time.

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.