Scaladoc Member Filter Enhancement (RC1)

Could you explain what changes were made? Some are obvious to me, but
I might be missing others.

On Fri, Jun 24, 2011 at 16:53, Rüdiger Keller
wrote:
> Hi,
>
> I "finished" my work on the member filter enhancement. Here are some
> cases to look at:
>
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala....
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Either$
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Predef$
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala....
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.collection.Seq$
>
> Everything should be fine now. I changed the structure of the
> generated html somewhat, therefore I had to adapt some tests.
>
> Please let me know about any bugs you encounter.
>
> If there are no objections, I will create a ticket & patch tomorrow.
>
> Regards,
> Rüdiger
>

After seeing http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Int I'd totally like to see an awesome scala-related 404!

-Doug Tangren
http://lessis.me


On Fri, Jun 24, 2011 at 4:12 PM, Daniel Sobral <dcsobral@gmail.com> wrote:

Could you explain what changes were made? Some are obvious to me, but
I might be missing others.

On Fri, Jun 24, 2011 at 16:53, Rüdiger Keller
<ruediger.keller@googlemail.com> wrote:
> Hi,
>
> I "finished" my work on the member filter enhancement. Here are some
> cases to look at:
>
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Either
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Either$
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Predef$
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.collection.Seq
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.collection.Seq$
>
> Everything should be fine now. I changed the structure of the
> generated html somewhat, therefore I had to adapt some tests.
>
> Please let me know about any bugs you encounter.
>
> If there are no objections, I will create a ticket & patch tomorrow.
>
> Regards,
> Rüdiger
>



--
Daniel C. Sobral

I travel to the future all the time.

Ha ha ha! Awesome!

I'd like to say that I totally pimped the 404 error page, but actually
I only uploaded the aforementioned pages. ;-)

Regards,
Rüdiger

2011/6/25 Doug Tangren :
> After seeing
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Int
> I'd totally like to see an awesome scala-related 404!
>
> -Doug Tangren
> http://lessis.me
>
>
> On Fri, Jun 24, 2011 at 4:12 PM, Daniel Sobral wrote:
>>
>> Could you explain what changes were made? Some are obvious to me, but
>> I might be missing others.
>>
>> On Fri, Jun 24, 2011 at 16:53, Rüdiger Keller
>> wrote:
>> > Hi,
>> >
>> > I "finished" my work on the member filter enhancement. Here are some
>> > cases to look at:
>> >
>> >
>> > http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala....
>> >
>> > http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Either$
>> >
>> > http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Predef$
>> >
>> > http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala....
>> >
>> > http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.collection.Seq$
>> >
>> > Everything should be fine now. I changed the structure of the
>> > generated html somewhat, therefore I had to adapt some tests.
>> >
>> > Please let me know about any bugs you encounter.
>> >
>> > If there are no objections, I will create a ticket & patch tomorrow.
>> >
>> > Regards,
>> > Rüdiger
>> >
>>
>>
>>
>> --
>> Daniel C. Sobral
>>
>> I travel to the future all the time.
>
>

Ok, I guess that's not unreasonable.

The changes of the patch relative to trunk are:

- The member filter section moved from the page itself to the bar at
the top. The elements changed, but all functionality is still there
(else it's a bug).
- I improved the text based member filter. The text input field is
automatically focused once you start typing, regardless of whether it
had the focus or not. Also, whenever filtering, the top of the member
section is scrolled into view.
- Text filtering is not using regular expression syntax anymore. This
means you can actually type "++" to search for members called "++".
Before, you needed to type "\+\+" to achieve this.
- Whitespace in the text filter is used to OR search terms. Typing
"fold reduce" shows all members containing either "fold" or "reduce".
- Filtering should be (way) faster than before. This is mostly
noticeable when using the text based filter on a large page, like
collection.Seq. On my system it is more than 3 times faster, IIRC.
- I removed some redundancy in the static html (removed "shortcomment"
divs). This is noticeable by the somewhat cleaner/smoother animation
when opening/closing members. Also, file size is somewhat smaller.
- Now, the first line of the comment is shown when a member is closed,
regardless of the comments content. Before, it showed the first
sentence, regardless of the sentences length. This usually means that
it shows more of the comment than before (depending on window width).
- I did some smaller tweaks to the CSS. For example, attributes and
parameter descriptions are now aligned.

Regards,
Rüdiger

2011/6/24 Daniel Sobral :
> Could you explain what changes were made? Some are obvious to me, but
> I might be missing others.
>
> On Fri, Jun 24, 2011 at 16:53, Rüdiger Keller
> wrote:
>> Hi,
>>
>> I "finished" my work on the member filter enhancement. Here are some
>> cases to look at:
>>
>> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala....
>> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Either$
>> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Predef$
>> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala....
>> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.collection.Seq$
>>
>> Everything should be fine now. I changed the structure of the
>> generated html somewhat, therefore I had to adapt some tests.
>>
>> Please let me know about any bugs you encounter.
>>
>> If there are no objections, I will create a ticket & patch tomorrow.
>>
>> Regards,
>> Rüdiger
>>
>
>
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

Hi Ruediger,

looks really good!

Could you explain the reason why the filter/search bar moved to the top?
(Sorry, if you already did and I missed it.)

I liked the old layout a bit better, but maybe I just have to adapt a bit...

Bye,

Simon

Well, I had complaints from people, that wanted to have it at the top,
so there goes.

At least now it aligns with the search bar of the package frame, so
regarding consistency it's an improvement.

Regards,
Rüdiger

2011/6/25 Simon Ochsenreither :
> Hi Ruediger,
>
> looks really good!
>
> Could you explain the reason why the filter/search bar moved to the top?
> (Sorry, if you already did and I missed it.)
>
> I liked the old layout a bit better, but maybe I just have to adapt a bit...
>
> Bye,
>
>
> Simon
>

On Sat, Jun 25, 2011 at 08:58, Simon Ochsenreither
wrote:
> Hi Ruediger,
>
> looks really good!
>
> Could you explain the reason why the filter/search bar moved to the top?
> (Sorry, if you already did and I missed it.)

I bitched and screamed until I got my way! :-)

Though I prefer it that way, either it or the class search box had to
move. Having one on the top and the other on the bottom was just...
not right. :-)

I created a ticket and attached the patch:

https://issues.scala-lang.org/browse/SI-4736

Regards,
Rüdiger

2011/6/24 Rüdiger Keller :
> Hi,
>
> I "finished" my work on the member filter enhancement. Here are some
> cases to look at:
>
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala....
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Either$
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.Predef$
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala....
> http://dl.dropbox.com/u/21541067/415073477859211068427/index.html#scala.collection.Seq$
>
> Everything should be fine now. I changed the structure of the
> generated html somewhat, therefore I had to adapt some tests.
>
> Please let me know about any bugs you encounter.
>
> If there are no objections, I will create a ticket & patch tomorrow.
>
> Regards,
> Rüdiger
>

Hi,

> Well, I had complaints from people, that wanted to have it at the top,
> so there goes.
>
> At least now it aligns with the search bar of the package frame, so
> regarding consistency it's an improvement.

Mh... interesting. I asked because I felt it was inconsistent, the
class search at the left is on top of the things it changes.

With the new member filter design, there is now something completely
unrelated (the class description) between the search and the things it
modifies.

I would have prefered it to be on top of the things it actually
changes, but I'm not that opiniated here. I could just imagine that it
won't work that good anymore when Scala classes will get more
documentation, then the search and the members are on "different"
screen pages.

I don't know how complicated that would be, but I'd like to suggest
some compromise:
Would it be possible to leave the search where it is (above the
members) and when the user scrolls past it, it stays at the top of the
browser frame? (A bit like http://etorreborre.blogspot.com/ when you
scroll down and the top bar appears.) This would make it possible to
have the search at the top when the user is looking at the members,
but keeps the clutter away when the user reads the class documentation.
(My description isn't good, if someone has problems understanding,
I'll provide a picture ...)

Two minor suggestions:
a) "Ungroup by inheritance" ... I would suggest something like "Sort
alphabetically" which says more what it does instead of "undoing"
something else.
b) Is it possible to stop the buttons changing width when the text
inside of them changes?

Thanks for your great work!

Simon

Sorry for spamming ...

Just got an idea for a small usability improvement.

Would it be possible to have some light gray text in both search
fields which describe what they do, which disappears when the user
starts inputting text or clicks into it? (You know what I mean...)

Maybe for the left one "Type to filter class list" and the right one
"Type to flter class memebers"?

Thanks and bye,

Simon

Found a better example:

http://www.quora.com/What-programming-language-do-people-hate-the-most-a...

Have a look at the "upvote/downvote" butons on the left, which move
with you while scrolling if you scroll "past" them.

> I don't know how complicated that would be, but I'd like to suggest
> some compromise:
> Would it be possible to leave the search where it is (above the
> members) and when the user scrolls past it, it stays at the top of the
> browser frame? (A bit like http://etorreborre.blogspot.com/ when you
> scroll down and the top bar appears.)

Thanks and bye,

Simon

Hi Simon,

thanks for your feedback.

To be honest, I don't think it's worth the effort to implement the
filter bar positioning the way you describe. Sure it's possible, but
IMHO the gain is little. I didn't like it at the top for the same
reasons, at first. But when "everyone" complained I moved it to the
top regardless and now I don't bother anymore.

Also, when you want to immediately search for members, it's nice that
the filter bar as always visible, without first scrolling down to the
members. Actually that was one of my goals of the new design. IIRC,
Scalatest has some ultra long class descriptions, so it's especially
useful there, for example.

> "Ungroup by inheritance" ... I would suggest something like "Sort alphabetically"

Yes, "ungroup" doesn't sound right. But the members are always sorted
alphabetically, whether grouped or not. Therefore IMHO "Sort
alphabetically" doesn't properly describe what's changing.

> Is it possible to stop the buttons changing width when the text inside of them changes?

Sure is.

> Would it be possible to have some light gray text in both search fields [...]

Yep, I agree.

But actually I don't feel like modifying the patch any more. I have
already spent way more time on it than originally anticipated. Please
open an enhancement ticket with your suggested changes, and whoever
feels like it can implement them once the current patch is applied
(might well be me again for the minor things).

Regards,
Rüdiger

2011/6/25 Simon Ochsenreither :
> Hi,
>
>> Well, I had complaints from people, that wanted to have it at the top,
>> so there goes.
>>
>> At least now it aligns with the search bar of the package frame, so
>> regarding consistency it's an improvement.
>
> Mh... interesting. I asked because I felt it was inconsistent, the class
> search at the left is on top of the things it changes.
>
> With the new member filter design, there is now something completely
> unrelated (the class description) between the search and the things it
> modifies.
>
> I would have prefered it to be on top of the things it actually changes, but
> I'm not that opiniated here. I could just imagine that it won't work that
> good anymore when Scala classes will get more documentation, then the search
> and the members are on "different" screen pages.
>
> I don't know how complicated that would be, but I'd like to suggest some
> compromise:
> Would it be possible to leave the search where it is (above the members) and
> when the user scrolls past it, it stays at the top of the browser frame? (A
> bit like http://etorreborre.blogspot.com/ when you scroll down and the top
> bar appears.) This would make it possible to have the search at the top when
> the user is looking at the members, but keeps the clutter away when the user
> reads the class documentation.
> (My description isn't good, if someone has problems understanding, I'll
> provide a picture ...)
>
> Two minor suggestions:
> a) "Ungroup by inheritance" ... I would suggest something like "Sort
> alphabetically" which says more what it does instead of "undoing" something
> else.
> b) Is it possible to stop the buttons changing width when the text inside of
> them changes?
>
> Thanks for your great work!
>
>
> Simon
>
>

Hello Rüdiger.
I really like your new & improved search bar and improved text search.
I agree with some of the ideas to tweak the design even further. For example to have the search bar be located where it was before (between class description and members) but have it stick at the top when scrolling the page. Another thing that I would have probably done differently is to use toggle buttons rather than normal buttons that change label depending on their state. But I don't think these tweaks are critical and they can easily be done in a later update, if wanted.
I saw you created an improvement with the patch. Is this the version you want to commit to trunk for now, or do you still want to tweak it further?
Cheers,Gilles.

Hi Gilles,

nice to hear from you. The patch attached to the ticket is the version
I would like to see committed.

I agree that further teaks can be done once the patch is committed.
Then others can work on it, too.

Regarding the position of the filter bar, I'm not sure if the
suggestion is an improvement. As I said earlier, I want to enable the
filter-at-once use case and that is better served by an always visible
filter bar, IMHO. But perhaps someone can prototype it and we can see
how it "feels". That's best for judging how to proceed. :-)

Regards,
Rüdiger

2011/6/28 Gilles Dubochet :
> Hello Rüdiger.
> I really like your new & improved search bar and improved text search.
> I agree with some of the ideas to tweak the design even further. For example
> to have the search bar be located where it was before (between class
> description and members) but have it stick at the top when scrolling the
> page. Another thing that I would have probably done differently is to use
> toggle buttons rather than normal buttons that change label depending on
> their state. But I don't think these tweaks are critical and they can easily
> be done in a later update, if wanted.
> I saw you created an improvement with the patch. Is this the version you
> want to commit to trunk for now, or do you still want to tweak it further?
> Cheers,
> Gilles.