Request for comments on Scaladoc 2 entity search bar

When one selects "display packages only", the packages should change from "hide" to "show". As it is, I can click "hide", which will change it to "show", and then "show" to have it display that package. I like that behavior, but clicking "hide" first is meaningless when there are only packages being shown.

On Mon, Feb 15, 2010 at 12:03 PM, Gilles Dubochet <gilles.dubochet@epfl.ch> wrote:

Hello.

There have been significant improvements to the entity search bar (left bar) in Scaladoc 2 nightly builds over the last few days.

http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html

See the change log here:

http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Log

I would like to hear comments on the bar's current behaviour. Particularly, I would like to know whether there are usage scenarios related to searching for entities that remain unsatisfactory despite using the text filter, "display packages only", and "focus" tools.

Also, as always, contributions are welcome:

http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Contribute

Thanks,
Gilles.

--
Daniel C. Sobral

I travel to the future all the time.

Hello Daniel.

> When one selects "display packages only", the packages should change from "hide" to "show". As it is, I can click "hide", which will change it to "show", and then "show" to have it display that package. I like that behavior, but clicking "hide" first is meaningless when there are only packages being shown.

You are right: this is a bit buggy. Thanks for the report.

Now that you mention that, I also wonder what should happen when filtering in “display packages only” mode. The current behaviour is a bit strange: it filters packages according to whether they contain an entity that matches the filter. I am not sure this is the best solution.

A more logical solution would be to filter only on package names (although this only makes sense in large libraries with lots of packages). Another solution would be to always revert to “display all entities” mode when filtering.

What do you think?

Cheers,
Gilles.

>> There have been significant improvements to the entity search bar (left bar) in Scaladoc 2 nightly builds over the last few days.
>>
>> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...
>>
>> See the change log here:
>>
>> http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Log
>>
>> I would like to hear comments on the bar's current behaviour. Particularly, I would like to know whether there are usage scenarios related to searching for entities that remain unsatisfactory despite using the text filter, "display packages only", and "focus" tools.
>>
>> Also, as always, contributions are welcome:
>>
>> http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Contribute

On Monday February 15 2010, Gilles Dubochet wrote:
> Hello.
>
> There have been significant improvements to the entity search bar
> (left bar) in Scaladoc 2 nightly builds over the last few days.
>
> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/do
>cs/library/index.html

> See the change log here:
>
> http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Log
>
> I would like to hear comments on the bar's current behaviour. ...

Whatever has changed (beyond the visible UI elements associated with the
filter text field), the time required to filter the package / class
pane is now vastly more than it was in the Beta1 version of the docs.
To me, the degradation in speed is unacceptable. (And this is using
Chrome, presumably one of the faster JavaScript interpreters going.)

There are apparently some bugs in the handling of the field's contents
as it interacts with editing the field. If you make a mid-word edit
(say, to correct a typo) the filter is not refreshed until you use an
arrow key.

As with the previous ScalaDoc2, it remains too difficult to discover in
which class along the inheritance lattice a particular method is
introduced. The inheritance filter buttons (which, by the way, show no
visual cues that they're active elements) are insufficient because they
force you to guess and try to figure out which one(s) contribute the
method in question. The approach of JavaDoc and the original ScalaDoc
seem preferable to me.

As a rule, I dislike tooltips. They're visually extremely noisy once
they trip, and in the current version there appears to be no delay at
all between the pointer entering the abbreviated name and the
tool-tip's appearance.

I'd might prefer some criteria distinguishing which type names are
displayed in an abbreviated form (with expansion to their full
expression or a tool-tip showing that expression displayed upon
time-delayed hover) and which are displayed fully all the time.

> Also, as always, contributions are welcome:
>
> http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Contribute
>
> Thanks,
> Gilles.

Randall Schulz

I don't mind at all the current behavior, to be honest. I can always expand the packages I'm interested in.

On Mon, Feb 15, 2010 at 1:07 PM, Gilles Dubochet <gilles.dubochet@epfl.ch> wrote:

Hello Daniel.

> When one selects "display packages only", the packages should change from "hide" to "show". As it is, I can click "hide", which will change it to "show", and then "show" to have it display that package. I like that behavior, but clicking "hide" first is meaningless when there are only packages being shown.

You are right: this is a bit buggy. Thanks for the report.

Now that you mention that, I also wonder what should happen when filtering in “display packages only” mode. The current behaviour is a bit strange: it filters packages according to whether they contain an entity that matches the filter. I am not sure this is the best solution.

A more logical solution would be to filter only on package names (although this only makes sense in large libraries with lots of packages). Another solution would be to always revert to “display all entities” mode when filtering.

What do you think?

Cheers,
Gilles.

>> There have been significant improvements to the entity search bar (left bar) in Scaladoc 2 nightly builds over the last few days.
>>
>> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html
>>
>> See the change log here:
>>
>> http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Log
>>
>> I would like to hear comments on the bar's current behaviour. Particularly, I would like to know whether there are usage scenarios related to searching for entities that remain unsatisfactory despite using the text filter, "display packages only", and "focus" tools.
>>
>> Also, as always, contributions are welcome:
>>
>> http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Contribute

--
Daniel C. Sobral

I travel to the future all the time.

> As with the previous ScalaDoc2, it remains too difficult to discover in

> which class along the inheritance lattice a particular method is
> introduced. The inheritance filter buttons (which, by the way, show no
> visual cues that they're active elements) are insufficient because they
> force you to guess and try to figure out which one(s) contribute the
> method in question. The approach of JavaDoc and the original ScalaDoc
> seem preferable to me.

The “definition classes” entry in a member's documentation is a list of all parents in which a given member has been declared or overridden.

For example, method drop in class List has:

> definition classes: List ⇐ LinearSeqLike ⇐ TraversableLike

This means that drop is declared in List itself, and that this declaration overrides that in LinearSeqLike, and so on.

Method distinct, on the other hand, has:

> definition classes: SeqLike

This means that it is inherited from trait SeqLike, where it was defined for the first time.

Were you unaware of this feature or did I misunderstand the information you are looking for?

> There are apparently some bugs in the handling of the field's contents
> as it interacts with editing the field. If you make a mid-word edit
> (say, to correct a typo) the filter is not refreshed until you use an
> arrow key.

I can't seem to reproduce this issue. Can you give more information on it.

As for the other points you raise, as always, considering the limited resource available, there is not much I can do rapidly. The performance issue has to do with the fact that filtering is now non-blocking, which slows down filtering. Oddly, this was absolutely required for users with slower browsers/machines to prevent their browser freezing. I am sure that performance could be improved, but I lack the necessary expertise and time.

Cheers,
Gilles

This is how I believe the search bar should behave:

1). Always default to "Show packages only" (i.e. package members are hidden)
2). As soon as typing starts, revert to "Expand to all members"

The reason for this is that the most likely usage of the navigation is to either allow the user to click on a package, or to allow a user to click on a class/object/trait depending on what they have entered in the search bar. The behaviour above allows for this to happen with the minimum of user input

Chris

> From: gilles.dubochet@epfl.ch
> Subject: [scala-internals] Request for comments on Scaladoc 2 entity search bar
> Date: Mon, 15 Feb 2010 15:03:51 +0100
> To: scala-internals@listes.epfl.ch
>
> Hello.
>
> There have been significant improvements to the entity search bar (left bar) in Scaladoc 2 nightly builds over the last few days.
>
> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...
>
> See the change log here:
>
> http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Log
>
> I would like to hear comments on the bar's current behaviour. Particularly, I would like to know whether there are usage scenarios related to searching for entities that remain unsatisfactory despite using the text filter, "display packages only", and "focus" tools.
>
> Also, as always, contributions are welcome:
>
> http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Contribute
>
> Thanks,
> Gilles.
>

Do you have a story that started on Hotmail? Tell us now

On Monday February 15 2010, Gilles Dubochet wrote:
> > As with the previous ScalaDoc2, it remains too difficult to
> > discover in
> >
> > which class along the inheritance lattice a particular method is
> > introduced. The inheritance filter buttons (which, by the way, show
> > no visual cues that they're active elements) are insufficient
> > because they force you to guess and try to figure out which one(s)
> > contribute the method in question. The approach of JavaDoc and the
> > original ScalaDoc seem preferable to me.
>
> The “definition classes” entry in a member's documentation is a list
> of all parents in which a given member has been declared or
> overridden.
>
> ...
>
> Were you unaware of this feature or did I misunderstand the
> information you are looking for?

I was unaware of it. This is actually better than JavaDoc or the
original ScalaDoc.

> > There are apparently some bugs in the handling of the field's
> > contents as it interacts with editing the field. If you make a
> > mid-word edit (say, to correct a typo) the filter is not refreshed
> > until you use an arrow key.
>
> I can't seem to reproduce this issue. Can you give more information
> on it.

It seems that the bug is triggered when you overwrite characters (i.e.,
type when the selection is _not_ an insertion point), but not when you
insert or delete them (type when the selection _is_ an insertion
point).

> ...
>
> Cheers,
> Gilles

Randall Schulz

That behavior sounds good, indeed -- as long as one an revert to expand to all members without having to search.

On Tue, Feb 16, 2010 at 12:42 PM, christopher marshall <oxbow_lakes@hotmail.com> wrote:

This is how I believe the search bar should behave:

1). Always default to "Show packages only" (i.e. package members are hidden)
2). As soon as typing starts, revert to "Expand to all members"

The reason for this is that the most likely usage of the navigation is to either allow the user to click on a package, or to allow a user to click on a class/object/trait depending on what they have entered in the search bar. The behaviour above allows for this to happen with the minimum of user input

Chris

> From: gilles.dubochet@epfl.ch
> Subject: [scala-internals] Request for comments on Scaladoc 2 entity search bar
> Date: Mon, 15 Feb 2010 15:03:51 +0100
> To: scala-internals@listes.epfl.ch
>
> Hello.
>
> There have been significant improvements to the entity search bar (left bar) in Scaladoc 2 nightly builds over the last few days.
>
> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html
>
> See the change log here:
>
> http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Log
>
> I would like to hear comments on the bar's current behaviour. Particularly, I would like to know whether there are usage scenarios related to searching for entities that remain unsatisfactory despite using the text filter, "display packages only", and "focus" tools.
>
> Also, as always, contributions are welcome:
>
> http://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Contribute
>
> Thanks,
> Gilles.
>

Do you have a story that started on Hotmail? Tell us now

--
Daniel C. Sobral

I travel to the future all the time.

I agree, this all sounds very reasonable. If no one complains about it soon, it will probably be part of the next batch of updates to the entity search bar of Scaladoc 2.

> That behavior sounds good, indeed -- as long as one an revert to expand to all members without having to search.
>
>> This is how I believe the search bar should behave:
>>
>> 1). Always default to "Show packages only" (i.e. package members are hidden)
>> 2). As soon as typing starts, revert to "Expand to all members"