Scaladoc enhancements: searching members and further ideas

On Sun, May 15, 2011 at 10:56 AM, Rüdiger Keller <ruediger.keller@googlemail.com> wrote:

I made some changes to Scaladoc to improve searching/filtering
members. IMHO this improves the "search" use case quite a lot.

Looks great!  I love the idea of keyboard-navigable documentation, so...
- It'd be nice to be able to use arrow keys to navigate the lists of packages/members - Pressing Enter in the search box should go into arrow-navigation mode, and maybe expand the first/selected item at the same time- If you have more than one search result, the Up/Down arrow keys should let you navigate between them, and pressing Enter should expand the currently selected one. - If you're arrow-navigating in the package/class list and you press enter, the browser does the right thing and loads the selected class in the right frame.  But to take it a step further, the keyboard focus should be placed into the right frame so that you can use arrow keys to scroll up and down the members of the class. - If you press Escape when you're not in the search textbox, you should go "back", e.g.:  * from navigating members of a class to the list of classes  * from the list of classes to the class search box.
Great work!  I think we're well on the way to having the nicest-looking and most usable API docs anywhere!   Now if only they were in the running for most complete... ;)
-0xe1a

I don't know if they are part of the standard 2.9 docs, but I love the look of the "buttons" that select what parts of documentation are visible--it's much more obvious now that they should be clicked on!

Ken

On May 15, 2011, at 12:56 PM, Rüdiger Keller wrote:

Indeed, arrow key navigation sounds like a "good thing". Also, you
bring up some nice ideas how to realize it. I will probably explore
the idea on my next run.

And thank you for praising the changes! :-)

Regards,
Rüdiger

2011/5/15 Alex Cruise :
> On Sun, May 15, 2011 at 10:56 AM, Rüdiger Keller
> wrote:
>>
>> I made some changes to Scaladoc to improve searching/filtering
>> members. IMHO this improves the "search" use case quite a lot.
>
> Looks great!  I love the idea of keyboard-navigable documentation, so...
> - It'd be nice to be able to use arrow keys to navigate the lists of
> packages/members
> - Pressing Enter in the search box should go into arrow-navigation mode, and
> maybe expand the first/selected item at the same time
> - If you have more than one search result, the Up/Down arrow keys should let
> you navigate between them, and pressing Enter should expand the currently
> selected one.
> - If you're arrow-navigating in the package/class list and you press enter,
> the browser does the right thing and loads the selected class in the right
> frame.  But to take it a step further, the keyboard focus should be placed
> into the right frame so that you can use arrow keys to scroll up and down
> the members of the class.
> - If you press Escape when you're not in the search textbox, you should go
> "back", e.g.:
>   * from navigating members of a class to the list of classes
>   * from the list of classes to the class search box.
> Great work!  I think we're well on the way to having the nicest-looking and
> most usable API docs anywhere!   Now if only they were in the running for
> most complete... ;)
> -0xe1a

The buttons are already like this since 2.9.0. It's not something I
have done. ;-)

2011/5/15 Kenneth McDonald :
> I don't know if they are part of the standard 2.9 docs, but I love the look of the "buttons" that select what parts of documentation are visible--it's much more obvious now that they should be clicked on!
>
> Ken
>
> On May 15, 2011, at 12:56 PM, Rüdiger Keller wrote:
>
>
>

IMHO,

On Sun, May 15, 2011 at 14:56, Rüdiger Keller
wrote:
> Hi,
>
> I made some changes to Scaladoc to improve searching/filtering
> members. IMHO this improves the "search" use case quite a lot.
>
> You can try it on the following url, but beware that I only uploaded
> the docs for Seq and no other classes:
> http://dl.dropbox.com/u/21541067/038918640814529583732/index.html#scala....
>
> The Changes:
>  - The member filter box moved to a fixed position on the bottom right.

Hate it. I just don't see it anymore on my 23" screen. In my own
opinion, it should be moved below the package/trait/class/object
declaration (ie, below "trait Seq [+A] ..."), and everything down to
it should be locked against scrolling.

>  - The member filter box is selected when the page finishes loading.
>  - Typing while the right frame is active focuses the member filter box.
>   This means that you will always type into the member filter box,
> regardless of
>   whether it's focused or not, as long as the right frame is selected/focused.

Great.

>  - Using the member filter scrolls the results into view (seems to
> broken on IE8).

I like it.

>  - The member filter kicks in only after you haven't typed for 600ms.
> This makes typing
>   in the member filter box much smoother.

To me, it only makes me wait longer to see the results. I like how it
work today. If changed at all, the wait should be much lower -- if you
spend more than 200ms without typing something, it is not the computer
that is going to slow you down.

>  - Made shortcomment div on members unnecessary by showing the first line of the
>   fullcomment instead. Fixes the flickering animation when opening members and
>   reduces html size (not yet reflected in html).

No clue what that means.

>  - Various small layout adjustments.

Parameters on "Seq.flatten" look clearly better on your version. On
the official version, "asTraversable" actually runs up into the
description space. Plus, having the parameters and Definitions
classes/Annotations aligned is nice.

>
> Known issues:
>  - The spacing between [use case] and the text/comment below it is too small.

In fact, nothing shows in flatten's use case line.

>
> Not changed but noteworthy:
>  - Pressing ESC resets the member filter.

I'd like that.

>  - The member filter uses regexes, therefore you can OR search
> expressions by using
>   vertical bars: "fold|reduce". This is nice for comparing members.

IIRC, the first scaladoc 2 _did_ use regex, but it was dropped. And,
to be honest, regex searching is really way too much. Perhaps it would
be better if space-separated words were joined into or searching -- it
would solve the most common use case, avoid regex problems, and be
relatively intuitive.

>
> Further ideas:
>  - How should use cases be presented? The current solution is very
> lacking, IMHO.
>   One idea was to put "use case" before the def in the signature
> instead of inside
>   the comment.

Still waiting for something that does the job better. If you think you
have it, show-case it!

>  - Should a tooltip be added to the member filter for giving some
> help, e.g. stating
>   that it accepts regular expressions?

Maybe, but I don't see much use. People who are lost are unlikely to
search for tool tips for help.

>  - Should we introduce new syntax for the filter box that's not based
> on regexes to be able to
>   easier search for members with operator-like names and for ANDing
> search terms?
>   Examples: "++ AND use case", "fold OR reduce"

IMHO, keep it simple. Simple searches are probably more than 99%.
Avoid detracting from it.

Besides, text search is of only so much use. What Scaladoc is really
missing right now is type-based search.

>  - Should we have a switch for being able to search member names only, instead
>   of the full comments? Should this be the default?

Tell you what. If you move the search box up, you can put a "search
options" on the right side, where you can tweak the search to your
heart's content, and still keep it simple for the common case.

Lots of things! Haven't checked everything yet, but so I agree with
Daniel regarding filter box position.

On 15 maio, 20:17, Daniel Sobral wrote:
> IMHO,
>
> On Sun, May 15, 2011 at 14:56, Rüdiger Keller
>
> wrote:
> > Hi,
>
> > I made some changes to Scaladoc to improve searching/filtering
> > members. IMHO this improves the "search" use case quite a lot.
>
> > You can try it on the following url, but beware that I only uploaded
> > the docs for Seq and no other classes:
> >http://dl.dropbox.com/u/21541067/038918640814529583732/index.html#sca...
>
> > The Changes:
> >  - The member filter box moved to a fixed position on the bottom right.
>
> Hate it. I just don't see it anymore on my 23" screen. In my own
> opinion, it should be moved below the package/trait/class/object
> declaration (ie, below "trait Seq [+A] ..."), and everything down to
> it should be locked against scrolling.
>
> >  - The member filter box is selected when the page finishes loading.
> >  - Typing while the right frame is active focuses the member filter box.
> >   This means that you will always type into the member filter box,
> > regardless of
> >   whether it's focused or not, as long as the right frame is selected/focused.
>
> Great.
>
> >  - Using the member filter scrolls the results into view (seems to
> > broken on IE8).
>
> I like it.
>
> >  - The member filter kicks in only after you haven't typed for 600ms.
> > This makes typing
> >   in the member filter box much smoother.
>
> To me, it only makes me wait longer to see the results. I like how it
> work today. If changed at all, the wait should be much lower -- if you
> spend more than 200ms without typing something, it is not the computer
> that is going to slow you down.
>
> >  - Made shortcomment div on members unnecessary by showing the first line of the
> >   fullcomment instead. Fixes the flickering animation when opening members and
> >   reduces html size (not yet reflected in html).
>
> No clue what that means.
>
> >  - Various small layout adjustments.
>
> Parameters on "Seq.flatten" look clearly better on your version. On
> the official version, "asTraversable" actually runs up into the
> description space. Plus, having the parameters and Definitions
> classes/Annotations aligned is nice.
>
>
>
> > Known issues:
> >  - The spacing between [use case] and the text/comment below it is too small.
>
> In fact, nothing shows in flatten's use case line.
>
>
>
> > Not changed but noteworthy:
> >  - Pressing ESC resets the member filter.
>
> I'd like that.
>
> >  - The member filter uses regexes, therefore you can OR search
> > expressions by using
> >   vertical bars: "fold|reduce". This is nice for comparing members.
>
> IIRC, the first scaladoc 2 _did_ use regex, but it was dropped. And,
> to be honest, regex searching is really way too much. Perhaps it would
> be better if space-separated words were joined into or searching -- it
> would solve the most common use case, avoid regex problems, and be
> relatively intuitive.
>
>
>
> > Further ideas:
> >  - How should use cases be presented? The current solution is very
> > lacking, IMHO.
> >   One idea was to put "use case" before the def in the signature
> > instead of inside
> >   the comment.
>
> Still waiting for something that does the job better. If you think you
> have it, show-case it!
>
> >  - Should a tooltip be added to the member filter for giving some
> > help, e.g. stating
> >   that it accepts regular expressions?
>
> Maybe, but I don't see much use. People who are lost are unlikely to
> search for tool tips for help.
>
> >  - Should we introduce new syntax for the filter box that's not based
> > on regexes to be able to
> >   easier search for members with operator-like names and for ANDing
> > search terms?
> >   Examples: "++ AND use case", "fold OR reduce"
>
> IMHO, keep it simple. Simple searches are probably more than 99%.
> Avoid detracting from it.
>
> Besides, text search is of only so much use. What Scaladoc is really
> missing right now is type-based search.
>
> >  - Should we have a switch for being able to search member names only, instead
> >   of the full comments? Should this be the default?
>
> Tell you what. If you move the search box up, you can put a "search
> options" on the right side, where you can tweak the search to your
> heart's content, and still keep it simple for the common case.
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.

Hi Daniel,

> Hate it. I just don't see it anymore on my 23" screen. In my own
> opinion, it should be moved below the package/trait/class/object
> declaration (ie, below "trait Seq [+A] ..."), and everything down to
> it should be locked against scrolling.

I can not really follow the argumentation "I just don't see it
anymore". Do you think that the discoverability is bad or that you
just can't see it properly, even though you know it's there? Would it
help to make the box broader? Like half the frame's width or full
width?

Actually, at first I thought about doing exactly what you suggested,
but then I remembered that there are already people who hate the
current design for its "waste" of vertical space. These people would
certainly be furious with your suggestion. Also, I personally think
that it's using too much space for no apparent reason. I, at least,
never felt the need to look at the class signature when looking for
members.

Then I thought that I just put the filter box as a bar over the full
width of the window at the very top. But that just didn't look right
for me, so I put it to the bottom, where I liked it very much better.

Then reminded of the "vertical space waste haters" and I thought that
it's really not necessary for the filter box to take up the full width
of the frame. So making it smaller horizontally seemed like a good
idea, because it won't block as much of the important left part of the
screen where most of the documentation/signatures actually are.

Perhaps a compromise can be found? Like making it bigger, or even
taking the full width on the bottom. Perhaps I will put up some
variants for comparison. What do you think? When making it bigger the
space could be used more economically be putting some buttons or
something on it, see below.

>>  - The member filter kicks in only after you haven't typed for 600ms.
>> This makes typing
>>   in the member filter box much smoother.
>
> To me, it only makes me wait longer to see the results. I like how it
> work today. If changed at all, the wait should be much lower -- if you
> spend more than 200ms without typing something, it is not the computer
> that is going to slow you down.

Hmm, maybe I can try to tone it somewhat done from the current 600ms.
But I think this is really an improvement, especially on slower
computers/browsers. On IE8 it was a complete pain to use before.

Would it appease you if pressing ENTER would start the search immediately?

>
>>  - Made shortcomment div on members unnecessary by showing the first line of the
>>   fullcomment instead. Fixes the flickering animation when opening members and
>>   reduces html size (not yet reflected in html).
>
> No clue what that means.

Don't bother, it's about the html structure of the document. I thought
that maybe Donna would read this, she would know what it's about
because we discussed it before.

>> Known issues:
>>  - The spacing between [use case] and the text/comment below it is too small.
>
> In fact, nothing shows in flatten's use case line.

Good catch, I didn't notice. But I can easily fix this when adjusting
the html generation. For now I only worked with js & css.

> IIRC, the first scaladoc 2 _did_ use regex, but it was dropped. And,
> to be honest, regex searching is really way too much. Perhaps it would
> be better if space-separated words were joined into or searching -- it
> would solve the most common use case, avoid regex problems, and be
> relatively intuitive.

I agree that regexes are too much. I wonder when they were dropped
because in the current version of Scaladoc they are being used. That's
nothing I changed. I agree with the space-separated words suggestion.

>> Further ideas:
>>  - How should use cases be presented? The current solution is very
>> lacking, IMHO.
>>   One idea was to put "use case" before the def in the signature
>> instead of inside
>>   the comment.
>
> Still waiting for something that does the job better. If you think you
> have it, show-case it!

I don't really know. I wanted to hear ideas from you guys! :-D

>
>>  - Should a tooltip be added to the member filter for giving some
>> help, e.g. stating
>>   that it accepts regular expressions?
>
> Maybe, but I don't see much use. People who are lost are unlikely to
> search for tool tips for help.

I have a new idea. Replace the current "root package" page with a
general help page and put a nice and fat help button directing there
next to the filter box. Or is it currently actually possible to put
meaningful content onto the root package page?

> Besides, text search is of only so much use. What Scaladoc is really
> missing right now is type-based search.

That comes up time and again. Not sure how that should work, I haven't
worked with such a system before. I hear Haskell has a very nice type
search. But first I want to address the low hanging fruits.

>
>>  - Should we have a switch for being able to search member names only, instead
>>   of the full comments? Should this be the default?
>
> Tell you what. If you move the search box up, you can put a "search
> options" on the right side, where you can tweak the search to your
> heart's content, and still keep it simple for the common case.

Good idea.

Regards,
Rüdiger

Hey, 

> Besides, text search is of only so much use. What Scaladoc is really
> missing right now is type-based search.

That comes up time and again. Not sure how that should work, I haven't
worked with such a system before. I hear Haskell has a very nice type
search. But first I want to address the low hanging fruits.

Petr Hosek supervised a project to implement just that in Colladoc. It is still work in progress (for example, it can't deal with type variables, and the interface is still rough) but can already be quite useful. You can read more about it on Petr's website, read the documentation and check it out.
Cheers,Gilles.

Hey,

>>   One idea was to put "use case" before the def in the signature
>> instead of inside
>>   the comment.
>
> Still waiting for something that does the job better. If you think you
> have it, show-case it!

I don't really know. I wanted to hear ideas from you guys! :-D

My plan here, which Martin is also pushing for, is to only display use cases in the default members list, not the "real" signatures. The real stuff would be available only by clicking use-case members, as part of the extended comment. The point of use cases is to hide complexity; displaying both use case and original signature in the members list actually increases complexity, which is why we want them to be hidden at first. One could then add a filter to toggle display of simplified use-case signatures or full signatures, when needed by power users.
Let me know what you think of our plan.
Cheers,Gilles.

On Tue, May 17, 2011 at 20:44, Gilles Dubochet wrote:
> Hey,
>>
>> >>   One idea was to put "use case" before the def in the signature
>> >> instead of inside
>> >>   the comment.
>> >
>> > Still waiting for something that does the job better. If you think you
>> > have it, show-case it!
>>
>> I don't really know. I wanted to hear ideas from you guys! :-D
>
> My plan here, which Martin is also pushing for, is to only display use cases
> in the default members list, not the "real" signatures. The real stuff would
> be available only by clicking use-case members, as part of the extended
> comment. The point of use cases is to hide complexity; displaying both use
> case and original signature in the members list actually increases
> complexity, which is why we want them to be hidden at first. One could then
> add a filter to toggle display of simplified use-case signatures or full
> signatures, when needed by power users.
> Let me know what you think of our plan.

For myself, I always thought it would come to that. I can't say I'm
thrilled by it, for various reasons. First, the type signature it
presents doesn't exist -- if someone tries to use the type parameters
as presented, it won't work. Second, there's a lot of code that cannot
be explained by the use case (obviously), and I'm certain quite a few
people won't think of looking up the real signature. Third, people
might not realize they can use a method in a more flexible manner --
though I'm rather less concerned by that.

Since I can't think of an alternative, then I hope some consideration
is taken to minimize these risks.

I think that sounds like a good idea. This solution should definitely
be tried, so that it can be seen how it works in practice.

If nobody else is available for doing this, I would volunteer to
implement this. Although I would first like to "finish" my work on
member filtering.

Regards,
Rüdiger

2011/5/18 Gilles Dubochet :
> Hey,
>>
>> >>   One idea was to put "use case" before the def in the signature
>> >> instead of inside
>> >>   the comment.
>> >
>> > Still waiting for something that does the job better. If you think you
>> > have it, show-case it!
>>
>> I don't really know. I wanted to hear ideas from you guys! :-D
>
> My plan here, which Martin is also pushing for, is to only display use cases
> in the default members list, not the "real" signatures. The real stuff would
> be available only by clicking use-case members, as part of the extended
> comment. The point of use cases is to hide complexity; displaying both use
> case and original signature in the members list actually increases
> complexity, which is why we want them to be hidden at first. One could then
> add a filter to toggle display of simplified use-case signatures or full
> signatures, when needed by power users.
> Let me know what you think of our plan.
> Cheers,
> Gilles.
>