Re: Scaladoc2 suggestion to help with navigation to supertypes

I think it's worth saying that in "normal usage" one cares little about *exactly* where a method is inherited from as long as it is available. I think the current functionality is pretty good in this regard.

Chris

> Date: Sun, 28 Feb 2010 20:12:43 -0800
> Subject: Re: [scala-internals] Scaladoc2 suggestion to help with navigation to supertypes
> From: cay.horstmann@gmail.com
>
> How would you obtain all methods that mutable.IndexedSeqLike inherits
> from collection.IndexedSeqLike? With scaladoc2 you have to
>
> 1) Click "Hide All"
> 2) Click IndexedSeqLike



We want to hear all your funny, exciting and crazy Hotmail stories. Tell us now

mutable.IndexedSeqLike inherits all methods in collection.IndexedSeqLike. So all you have to do is go to collection.IndexedSeqLike. And, if you want just the methods _defined_ at collection.IndexedSeqLike, click on Hide All.
But Christopher has the right of it here. When you consider mutable.IndexedSeqLike, you are interested in what _it_ provides. If, for any method, you wonder what its descendency is, you just click on it and see its "definition classes".
The usage you describe is really more one of someone idly perusing Scala APIs than one that of someone writing code and needing help. Not that there's anything wrong with the former, but the new scaladoc is focused on the latter. It might help pointing that out. :-)

On Mon, Mar 1, 2010 at 1:12 AM, Cay Horstmann <cay.horstmann@gmail.com> wrote:

Ok, that's fine. In effect, it is the first group in the "grouped by
supertypes" list that I suggest.

How would you obtain all methods that mutable.IndexedSeqLike inherits
from collection.IndexedSeqLike? With scaladoc2 you have to

1) Click "Hide All"
2) Click IndexedSeqLike

Anyway, that really helps me out with my original problem--how not to
lose face in my presentation. I'll explain that "Hide All" is your
friend.

Thanks,

Cay



On Sun, Feb 28, 2010 at 5:04 PM, Daniel Sobral <dcsobral@gmail.com> wrote:
> The way I'd compare mutable.IndexedSeqLike with collection.IndexedSeqLike is
> to go to the former and hide all inherited methods. What's left is what is
> what mutable.IndexedSeqLike overrides or introduces,  Expanding them, one
> can see the definition classes for any method that is overridden.
> It works for me. What are your issues with it?
>
> On Sun, Feb 28, 2010 at 11:25 AM, Cay Horstmann <cay.horstmann@gmail.com>
> wrote:
>>
>> I do realize that, yes. But look at ArrayBuffer.
>>
>> class   ArrayBuffer[A] extends Buffer[A] with
>> GenericTraversableTemplate[A, ArrayBuffer[A][A]] with BufferLike[A,
>> ArrayBuffer[A]] with IndexedSeqLike[A, ArrayBuffer[A]] with Builder[A,
>> ArrayBuffer[A]] with ResizableArray[A]
>>
>> There are 6 direct supertypes (clickable) and 31 supertypes in the
>> "Inherits" list that are not clickable.
>>
>> How is someone who isn't intimately familiar with the internals of the
>> collections hierarchy going to know what to hide or show if you don't
>> let them discover it?
>>
>> In particular, when you pairs of indistinguishable "IndexedSeq
>> IndexedSeq", "IndexedSeqLike IndexedSeqLike", "Seq Seq", and "Iterable
>> Iterable".
>>
>> This brings up another problem with the Show/Hide concept. Look at
>> scala.collection.mutable.IndexedSeqLike. Let's say I want to know how
>> it differs from scala.collection.IndexedSeqLike.
>>
>> Here is the process:
>> - Go to scala.collection.mutable.IndexedSeqLike
>> - Scroll through all methods. On my screen, there are 8 pages of them.
>> - Use your photographic memory to memorize all of them
>> - Click the IndexedSeqLike button to hide them
>> - Scroll through all methods. On my screen, there are now 7 pages of them.
>> - Use your photographic memory to determine the difference
>>
>> Or am I missing something here?
>>
>> If not, the Show/Hide mechanism seems pretty worthless. It would be
>> more useful to  have a toggle that switches between alpha order and a
>> listing that is grouped by the supertypes.
>>
>> Cheers,
>>
>> Cay
>>
>>
>>
>>
>>
>> On Sat, Feb 27, 2010 at 6:22 AM, Daniel Sobral <dcsobral@gmail.com> wrote:
>> > You do realize you can click on the supertypes mentioned in the
>> > declaration
>> > itself, right below the class name, don't you?
>> >
>> > I'll beg to differ regarding the class toggling, though your suggestion
>> > has
>> > merit.
>> >
>> > On Fri, Feb 26, 2010 at 7:47 PM, Cay Horstmann <cay.horstmann@gmail.com>
>> > wrote:
>> >>
>> >> I am putting this on scala-internals because I was previously
>> >> admonished not to put scaladoc2 issues on scala-user.
>> >>
>> >> I am preparing a workshop for CS instructors interested in using Scala
>> >> for college courses. I am boldly using 2.8, which means scaladoc2. And
>> >> here is my problem. I want to go over some basic collections, such as
>> >> ArrayBuffer. But I can't figure out how to show the scaladoc2 page
>> >> without losing face.
>> >>
>> >> People will want to know the supertypes and their purpose. They will
>> >> want to *navigate* to them. That's much more important than the
>> >> hide/show behavior which is pretty worthless for a class with many
>> >> members and many supertypes (such as ArrayBuffer).
>> >>
>> >> ArrayBuffer is particularly embarrassing because it has two supertypes
>> >> Seq that appear indistinguishable. There is simply no way of finding
>> >> out what each of them is in the ArrayBuffer scaladoc2 page.
>> >>
>> >> So, here is my constructive suggestion.
>> >>
>> >> In the list of supertypes, make each type act like any other clickable
>> >> type, i.e. on mouse over show the package name and on click follow the
>> >> link to the type's page. AFTER each of the supertypes, put a checkbox
>> >> (or some other doohickey if you dislike checkboxes) to toggle the
>> >> show/hide status. Yes, it takes a small amount of additional real
>> >> estate, but it will be a HUGE improvement for usability.
>> >>
>> >> Thanks,
>> >>
>> >> Cay
>> >
>> >
>> >
>> > --
>> > Daniel C. Sobral
>> >
>> > I travel to the future all the time.
>> >
>
>
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

--
Daniel C. Sobral

I travel to the future all the time.

We have now come full circle.

Sure, all I have to do is go to collection.IndexedSeqLike.

I would love to have an easy way to go to collection.indexedSeqLike.

But how do I do that?

Not by clicking on IndexedSeqLike. That does something that you all
agree is rarely useful in practice, namely to hide exactly the methods
provided by that type.

My original request was to make the supertypes clickable links that
let you go to those types.

If there really is a use case for fine-grained showing/hiding by
supertype (and I agree that this is really more for someone idly
perusing Scala APIs), then provide that with checkboxes.

I don't think I am asking for something bizarre here. The original
Scaladoc (as well as Javadoc) have an easy way of getting at the
supertypes, and there is no reason that this functionality should be
taken away in scaladoc2, merely to have a feature for idle API
browsers.

Cheers,

Cay

On Mon, Mar 1, 2010 at 7:38 AM, Daniel Sobral wrote:
> mutable.IndexedSeqLike inherits all methods in collection.IndexedSeqLike. So
> all you have to do is go to collection.IndexedSeqLike. And, if you want just
> the methods _defined_ at collection.IndexedSeqLike, click on Hide All.
> But Christopher has the right of it here. When you consider
> mutable.IndexedSeqLike, you are interested in what _it_ provides. If, for
> any method, you wonder what its descendency is, you just click on it and see
> its "definition classes".
> The usage you describe is really more one of someone idly perusing Scala
> APIs than one that of someone writing code and needing help. Not that
> there's anything wrong with the former, but the new scaladoc is focused on
> the latter. It might help pointing that out. :-)
>
> On Mon, Mar 1, 2010 at 1:12 AM, Cay Horstmann
> wrote:
>>
>> Ok, that's fine. In effect, it is the first group in the "grouped by
>> supertypes" list that I suggest.
>>
>> How would you obtain all methods that mutable.IndexedSeqLike inherits
>> from collection.IndexedSeqLike? With scaladoc2 you have to
>>
>> 1) Click "Hide All"
>> 2) Click IndexedSeqLike
>>
>> Anyway, that really helps me out with my original problem--how not to
>> lose face in my presentation. I'll explain that "Hide All" is your
>> friend.
>>
>> Thanks,
>>
>> Cay
>>
>>
>>
>> On Sun, Feb 28, 2010 at 5:04 PM, Daniel Sobral wrote:
>> > The way I'd compare mutable.IndexedSeqLike with
>> > collection.IndexedSeqLike is
>> > to go to the former and hide all inherited methods. What's left is what
>> > is
>> > what mutable.IndexedSeqLike overrides or introduces,  Expanding them,
>> > one
>> > can see the definition classes for any method that is overridden.
>> > It works for me. What are your issues with it?
>> >
>> > On Sun, Feb 28, 2010 at 11:25 AM, Cay Horstmann
>> >
>> > wrote:
>> >>
>> >> I do realize that, yes. But look at ArrayBuffer.
>> >>
>> >> class   ArrayBuffer[A] extends Buffer[A] with
>> >> GenericTraversableTemplate[A, ArrayBuffer[A][A]] with BufferLike[A,
>> >> ArrayBuffer[A]] with IndexedSeqLike[A, ArrayBuffer[A]] with Builder[A,
>> >> ArrayBuffer[A]] with ResizableArray[A]
>> >>
>> >> There are 6 direct supertypes (clickable) and 31 supertypes in the
>> >> "Inherits" list that are not clickable.
>> >>
>> >> How is someone who isn't intimately familiar with the internals of the
>> >> collections hierarchy going to know what to hide or show if you don't
>> >> let them discover it?
>> >>
>> >> In particular, when you pairs of indistinguishable "IndexedSeq
>> >> IndexedSeq", "IndexedSeqLike IndexedSeqLike", "Seq Seq", and "Iterable
>> >> Iterable".
>> >>
>> >> This brings up another problem with the Show/Hide concept. Look at
>> >> scala.collection.mutable.IndexedSeqLike. Let's say I want to know how
>> >> it differs from scala.collection.IndexedSeqLike.
>> >>
>> >> Here is the process:
>> >> - Go to scala.collection.mutable.IndexedSeqLike
>> >> - Scroll through all methods. On my screen, there are 8 pages of them.
>> >> - Use your photographic memory to memorize all of them
>> >> - Click the IndexedSeqLike button to hide them
>> >> - Scroll through all methods. On my screen, there are now 7 pages of
>> >> them.
>> >> - Use your photographic memory to determine the difference
>> >>
>> >> Or am I missing something here?
>> >>
>> >> If not, the Show/Hide mechanism seems pretty worthless. It would be
>> >> more useful to  have a toggle that switches between alpha order and a
>> >> listing that is grouped by the supertypes.
>> >>
>> >> Cheers,
>> >>
>> >> Cay
>> >>
>> >>
>> >>
>> >>
>> >>
>> >> On Sat, Feb 27, 2010 at 6:22 AM, Daniel Sobral
>> >> wrote:
>> >> > You do realize you can click on the supertypes mentioned in the
>> >> > declaration
>> >> > itself, right below the class name, don't you?
>> >> >
>> >> > I'll beg to differ regarding the class toggling, though your
>> >> > suggestion
>> >> > has
>> >> > merit.
>> >> >
>> >> > On Fri, Feb 26, 2010 at 7:47 PM, Cay Horstmann
>> >> >
>> >> > wrote:
>> >> >>
>> >> >> I am putting this on scala-internals because I was previously
>> >> >> admonished not to put scaladoc2 issues on scala-user.
>> >> >>
>> >> >> I am preparing a workshop for CS instructors interested in using
>> >> >> Scala
>> >> >> for college courses. I am boldly using 2.8, which means scaladoc2.
>> >> >> And
>> >> >> here is my problem. I want to go over some basic collections, such
>> >> >> as
>> >> >> ArrayBuffer. But I can't figure out how to show the scaladoc2 page
>> >> >> without losing face.
>> >> >>
>> >> >> People will want to know the supertypes and their purpose. They will
>> >> >> want to *navigate* to them. That's much more important than the
>> >> >> hide/show behavior which is pretty worthless for a class with many
>> >> >> members and many supertypes (such as ArrayBuffer).
>> >> >>
>> >> >> ArrayBuffer is particularly embarrassing because it has two
>> >> >> supertypes
>> >> >> Seq that appear indistinguishable. There is simply no way of finding
>> >> >> out what each of them is in the ArrayBuffer scaladoc2 page.
>> >> >>
>> >> >> So, here is my constructive suggestion.
>> >> >>
>> >> >> In the list of supertypes, make each type act like any other
>> >> >> clickable
>> >> >> type, i.e. on mouse over show the package name and on click follow
>> >> >> the
>> >> >> link to the type's page. AFTER each of the supertypes, put a
>> >> >> checkbox
>> >> >> (or some other doohickey if you dislike checkboxes) to toggle the
>> >> >> show/hide status. Yes, it takes a small amount of additional real
>> >> >> estate, but it will be a HUGE improvement for usability.
>> >> >>
>> >> >> Thanks,
>> >> >>
>> >> >> Cay
>> >> >
>> >> >
>> >> >
>> >> > --
>> >> > Daniel C. Sobral
>> >> >
>> >> > I travel to the future all the time.
>> >> >
>> >
>> >
>> >
>> > --
>> > Daniel C. Sobral
>> >
>> > I travel to the future all the time.
>> >
>
>
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

You go to collection.IndexedSeqLike by clicking on its link, which is shown right below the class name, at the top of the doc.

On Tue, Mar 2, 2010 at 5:06 PM, Cay Horstmann <cay.horstmann@gmail.com> wrote:

We have now come full circle.

Sure, all I have to do is go to collection.IndexedSeqLike.

I would love to have an easy way to go to collection.indexedSeqLike.

But how do I do that?

Not by clicking on IndexedSeqLike. That does something that you all
agree is rarely useful in practice, namely to hide exactly the methods
provided by that type.

My original request was to make the supertypes clickable links that
let you go to those types.

If there really is a use case for fine-grained showing/hiding by
supertype (and I agree that this is really more for someone idly
perusing Scala APIs), then provide that with checkboxes.

I don't think I am asking for something bizarre here. The original
Scaladoc (as well as Javadoc) have an easy way of getting at the
supertypes, and there is no reason that this functionality should be
taken away in scaladoc2, merely to have a feature for idle API
browsers.

Cheers,

Cay

On Mon, Mar 1, 2010 at 7:38 AM, Daniel Sobral <dcsobral@gmail.com> wrote:
> mutable.IndexedSeqLike inherits all methods in collection.IndexedSeqLike. So
> all you have to do is go to collection.IndexedSeqLike. And, if you want just
> the methods _defined_ at collection.IndexedSeqLike, click on Hide All.
> But Christopher has the right of it here. When you consider
> mutable.IndexedSeqLike, you are interested in what _it_ provides. If, for
> any method, you wonder what its descendency is, you just click on it and see
> its "definition classes".
> The usage you describe is really more one of someone idly perusing Scala
> APIs than one that of someone writing code and needing help. Not that
> there's anything wrong with the former, but the new scaladoc is focused on
> the latter. It might help pointing that out. :-)
>
> On Mon, Mar 1, 2010 at 1:12 AM, Cay Horstmann <cay.horstmann@gmail.com>
> wrote:
>>
>> Ok, that's fine. In effect, it is the first group in the "grouped by
>> supertypes" list that I suggest.
>>
>> How would you obtain all methods that mutable.IndexedSeqLike inherits
>> from collection.IndexedSeqLike? With scaladoc2 you have to
>>
>> 1) Click "Hide All"
>> 2) Click IndexedSeqLike
>>
>> Anyway, that really helps me out with my original problem--how not to
>> lose face in my presentation. I'll explain that "Hide All" is your
>> friend.
>>
>> Thanks,
>>
>> Cay
>>
>>
>>
>> On Sun, Feb 28, 2010 at 5:04 PM, Daniel Sobral <dcsobral@gmail.com> wrote:
>> > The way I'd compare mutable.IndexedSeqLike with
>> > collection.IndexedSeqLike is
>> > to go to the former and hide all inherited methods. What's left is what
>> > is
>> > what mutable.IndexedSeqLike overrides or introduces,  Expanding them,
>> > one
>> > can see the definition classes for any method that is overridden.
>> > It works for me. What are your issues with it?
>> >
>> > On Sun, Feb 28, 2010 at 11:25 AM, Cay Horstmann
>> > <cay.horstmann@gmail.com>
>> > wrote:
>> >>
>> >> I do realize that, yes. But look at ArrayBuffer.
>> >>
>> >> class   ArrayBuffer[A] extends Buffer[A] with
>> >> GenericTraversableTemplate[A, ArrayBuffer[A][A]] with BufferLike[A,
>> >> ArrayBuffer[A]] with IndexedSeqLike[A, ArrayBuffer[A]] with Builder[A,
>> >> ArrayBuffer[A]] with ResizableArray[A]
>> >>
>> >> There are 6 direct supertypes (clickable) and 31 supertypes in the
>> >> "Inherits" list that are not clickable.
>> >>
>> >> How is someone who isn't intimately familiar with the internals of the
>> >> collections hierarchy going to know what to hide or show if you don't
>> >> let them discover it?
>> >>
>> >> In particular, when you pairs of indistinguishable "IndexedSeq
>> >> IndexedSeq", "IndexedSeqLike IndexedSeqLike", "Seq Seq", and "Iterable
>> >> Iterable".
>> >>
>> >> This brings up another problem with the Show/Hide concept. Look at
>> >> scala.collection.mutable.IndexedSeqLike. Let's say I want to know how
>> >> it differs from scala.collection.IndexedSeqLike.
>> >>
>> >> Here is the process:
>> >> - Go to scala.collection.mutable.IndexedSeqLike
>> >> - Scroll through all methods. On my screen, there are 8 pages of them.
>> >> - Use your photographic memory to memorize all of them
>> >> - Click the IndexedSeqLike button to hide them
>> >> - Scroll through all methods. On my screen, there are now 7 pages of
>> >> them.
>> >> - Use your photographic memory to determine the difference
>> >>
>> >> Or am I missing something here?
>> >>
>> >> If not, the Show/Hide mechanism seems pretty worthless. It would be
>> >> more useful to  have a toggle that switches between alpha order and a
>> >> listing that is grouped by the supertypes.
>> >>
>> >> Cheers,
>> >>
>> >> Cay
>> >>
>> >>
>> >>
>> >>
>> >>
>> >> On Sat, Feb 27, 2010 at 6:22 AM, Daniel Sobral <dcsobral@gmail.com>
>> >> wrote:
>> >> > You do realize you can click on the supertypes mentioned in the
>> >> > declaration
>> >> > itself, right below the class name, don't you?
>> >> >
>> >> > I'll beg to differ regarding the class toggling, though your
>> >> > suggestion
>> >> > has
>> >> > merit.
>> >> >
>> >> > On Fri, Feb 26, 2010 at 7:47 PM, Cay Horstmann
>> >> > <cay.horstmann@gmail.com>
>> >> > wrote:
>> >> >>
>> >> >> I am putting this on scala-internals because I was previously
>> >> >> admonished not to put scaladoc2 issues on scala-user.
>> >> >>
>> >> >> I am preparing a workshop for CS instructors interested in using
>> >> >> Scala
>> >> >> for college courses. I am boldly using 2.8, which means scaladoc2.
>> >> >> And
>> >> >> here is my problem. I want to go over some basic collections, such
>> >> >> as
>> >> >> ArrayBuffer. But I can't figure out how to show the scaladoc2 page
>> >> >> without losing face.
>> >> >>
>> >> >> People will want to know the supertypes and their purpose. They will
>> >> >> want to *navigate* to them. That's much more important than the
>> >> >> hide/show behavior which is pretty worthless for a class with many
>> >> >> members and many supertypes (such as ArrayBuffer).
>> >> >>
>> >> >> ArrayBuffer is particularly embarrassing because it has two
>> >> >> supertypes
>> >> >> Seq that appear indistinguishable. There is simply no way of finding
>> >> >> out what each of them is in the ArrayBuffer scaladoc2 page.
>> >> >>
>> >> >> So, here is my constructive suggestion.
>> >> >>
>> >> >> In the list of supertypes, make each type act like any other
>> >> >> clickable
>> >> >> type, i.e. on mouse over show the package name and on click follow
>> >> >> the
>> >> >> link to the type's page. AFTER each of the supertypes, put a
>> >> >> checkbox
>> >> >> (or some other doohickey if you dislike checkboxes) to toggle the
>> >> >> show/hide status. Yes, it takes a small amount of additional real
>> >> >> estate, but it will be a HUGE improvement for usability.
>> >> >>
>> >> >> Thanks,
>> >> >>
>> >> >> Cay
>> >> >
>> >> >
>> >> >
>> >> > --
>> >> > Daniel C. Sobral
>> >> >
>> >> > I travel to the future all the time.
>> >> >
>> >
>> >
>> >
>> > --
>> > Daniel C. Sobral
>> >
>> > I travel to the future all the time.
>> >
>
>
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

--
Daniel C. Sobral

I travel to the future all the time.

That only works for the IMMEDIATE superclass.

On Tue, Mar 2, 2010 at 1:29 PM, Daniel Sobral wrote:
> You go to collection.IndexedSeqLike by clicking on its link, which is shown
> right below the class name, at the top of the doc.
>
> On Tue, Mar 2, 2010 at 5:06 PM, Cay Horstmann
> wrote:
>>
>> We have now come full circle.
>>
>> Sure, all I have to do is go to collection.IndexedSeqLike.
>>
>> I would love to have an easy way to go to collection.indexedSeqLike.
>>
>> But how do I do that?
>>
>> Not by clicking on IndexedSeqLike. That does something that you all
>> agree is rarely useful in practice, namely to hide exactly the methods
>> provided by that type.
>>
>> My original request was to make the supertypes clickable links that
>> let you go to those types.
>>
>> If there really is a use case for fine-grained showing/hiding by
>> supertype (and I agree that this is really more for someone idly
>> perusing Scala APIs), then provide that with checkboxes.
>>
>> I don't think I am asking for something bizarre here. The original
>> Scaladoc (as well as Javadoc) have an easy way of getting at the
>> supertypes, and there is no reason that this functionality should be
>> taken away in scaladoc2, merely to have a feature for idle API
>> browsers.
>>
>> Cheers,
>>
>> Cay
>>
>> On Mon, Mar 1, 2010 at 7:38 AM, Daniel Sobral wrote:
>> > mutable.IndexedSeqLike inherits all methods in
>> > collection.IndexedSeqLike. So
>> > all you have to do is go to collection.IndexedSeqLike. And, if you want
>> > just
>> > the methods _defined_ at collection.IndexedSeqLike, click on Hide All.
>> > But Christopher has the right of it here. When you consider
>> > mutable.IndexedSeqLike, you are interested in what _it_ provides. If,
>> > for
>> > any method, you wonder what its descendency is, you just click on it and
>> > see
>> > its "definition classes".
>> > The usage you describe is really more one of someone idly perusing Scala
>> > APIs than one that of someone writing code and needing help. Not that
>> > there's anything wrong with the former, but the new scaladoc is focused
>> > on
>> > the latter. It might help pointing that out. :-)
>> >
>> > On Mon, Mar 1, 2010 at 1:12 AM, Cay Horstmann
>> > wrote:
>> >>
>> >> Ok, that's fine. In effect, it is the first group in the "grouped by
>> >> supertypes" list that I suggest.
>> >>
>> >> How would you obtain all methods that mutable.IndexedSeqLike inherits
>> >> from collection.IndexedSeqLike? With scaladoc2 you have to
>> >>
>> >> 1) Click "Hide All"
>> >> 2) Click IndexedSeqLike
>> >>
>> >> Anyway, that really helps me out with my original problem--how not to
>> >> lose face in my presentation. I'll explain that "Hide All" is your
>> >> friend.
>> >>
>> >> Thanks,
>> >>
>> >> Cay
>> >>
>> >>
>> >>
>> >> On Sun, Feb 28, 2010 at 5:04 PM, Daniel Sobral
>> >> wrote:
>> >> > The way I'd compare mutable.IndexedSeqLike with
>> >> > collection.IndexedSeqLike is
>> >> > to go to the former and hide all inherited methods. What's left is
>> >> > what
>> >> > is
>> >> > what mutable.IndexedSeqLike overrides or introduces,  Expanding them,
>> >> > one
>> >> > can see the definition classes for any method that is overridden.
>> >> > It works for me. What are your issues with it?
>> >> >
>> >> > On Sun, Feb 28, 2010 at 11:25 AM, Cay Horstmann
>> >> >
>> >> > wrote:
>> >> >>
>> >> >> I do realize that, yes. But look at ArrayBuffer.
>> >> >>
>> >> >> class   ArrayBuffer[A] extends Buffer[A] with
>> >> >> GenericTraversableTemplate[A, ArrayBuffer[A][A]] with BufferLike[A,
>> >> >> ArrayBuffer[A]] with IndexedSeqLike[A, ArrayBuffer[A]] with
>> >> >> Builder[A,
>> >> >> ArrayBuffer[A]] with ResizableArray[A]
>> >> >>
>> >> >> There are 6 direct supertypes (clickable) and 31 supertypes in the
>> >> >> "Inherits" list that are not clickable.
>> >> >>
>> >> >> How is someone who isn't intimately familiar with the internals of
>> >> >> the
>> >> >> collections hierarchy going to know what to hide or show if you
>> >> >> don't
>> >> >> let them discover it?
>> >> >>
>> >> >> In particular, when you pairs of indistinguishable "IndexedSeq
>> >> >> IndexedSeq", "IndexedSeqLike IndexedSeqLike", "Seq Seq", and
>> >> >> "Iterable
>> >> >> Iterable".
>> >> >>
>> >> >> This brings up another problem with the Show/Hide concept. Look at
>> >> >> scala.collection.mutable.IndexedSeqLike. Let's say I want to know
>> >> >> how
>> >> >> it differs from scala.collection.IndexedSeqLike.
>> >> >>
>> >> >> Here is the process:
>> >> >> - Go to scala.collection.mutable.IndexedSeqLike
>> >> >> - Scroll through all methods. On my screen, there are 8 pages of
>> >> >> them.
>> >> >> - Use your photographic memory to memorize all of them
>> >> >> - Click the IndexedSeqLike button to hide them
>> >> >> - Scroll through all methods. On my screen, there are now 7 pages of
>> >> >> them.
>> >> >> - Use your photographic memory to determine the difference
>> >> >>
>> >> >> Or am I missing something here?
>> >> >>
>> >> >> If not, the Show/Hide mechanism seems pretty worthless. It would be
>> >> >> more useful to  have a toggle that switches between alpha order and
>> >> >> a
>> >> >> listing that is grouped by the supertypes.
>> >> >>
>> >> >> Cheers,
>> >> >>
>> >> >> Cay
>> >> >>
>> >> >>
>> >> >>
>> >> >>
>> >> >>
>> >> >> On Sat, Feb 27, 2010 at 6:22 AM, Daniel Sobral
>> >> >> wrote:
>> >> >> > You do realize you can click on the supertypes mentioned in the
>> >> >> > declaration
>> >> >> > itself, right below the class name, don't you?
>> >> >> >
>> >> >> > I'll beg to differ regarding the class toggling, though your
>> >> >> > suggestion
>> >> >> > has
>> >> >> > merit.
>> >> >> >
>> >> >> > On Fri, Feb 26, 2010 at 7:47 PM, Cay Horstmann
>> >> >> >
>> >> >> > wrote:
>> >> >> >>
>> >> >> >> I am putting this on scala-internals because I was previously
>> >> >> >> admonished not to put scaladoc2 issues on scala-user.
>> >> >> >>
>> >> >> >> I am preparing a workshop for CS instructors interested in using
>> >> >> >> Scala
>> >> >> >> for college courses. I am boldly using 2.8, which means
>> >> >> >> scaladoc2.
>> >> >> >> And
>> >> >> >> here is my problem. I want to go over some basic collections,
>> >> >> >> such
>> >> >> >> as
>> >> >> >> ArrayBuffer. But I can't figure out how to show the scaladoc2
>> >> >> >> page
>> >> >> >> without losing face.
>> >> >> >>
>> >> >> >> People will want to know the supertypes and their purpose. They
>> >> >> >> will
>> >> >> >> want to *navigate* to them. That's much more important than the
>> >> >> >> hide/show behavior which is pretty worthless for a class with
>> >> >> >> many
>> >> >> >> members and many supertypes (such as ArrayBuffer).
>> >> >> >>
>> >> >> >> ArrayBuffer is particularly embarrassing because it has two
>> >> >> >> supertypes
>> >> >> >> Seq that appear indistinguishable. There is simply no way of
>> >> >> >> finding
>> >> >> >> out what each of them is in the ArrayBuffer scaladoc2 page.
>> >> >> >>
>> >> >> >> So, here is my constructive suggestion.
>> >> >> >>
>> >> >> >> In the list of supertypes, make each type act like any other
>> >> >> >> clickable
>> >> >> >> type, i.e. on mouse over show the package name and on click
>> >> >> >> follow
>> >> >> >> the
>> >> >> >> link to the type's page. AFTER each of the supertypes, put a
>> >> >> >> checkbox
>> >> >> >> (or some other doohickey if you dislike checkboxes) to toggle the
>> >> >> >> show/hide status. Yes, it takes a small amount of additional real
>> >> >> >> estate, but it will be a HUGE improvement for usability.
>> >> >> >>
>> >> >> >> Thanks,
>> >> >> >>
>> >> >> >> Cay
>> >> >> >
>> >> >> >
>> >> >> >
>> >> >> > --
>> >> >> > Daniel C. Sobral
>> >> >> >
>> >> >> > I travel to the future all the time.
>> >> >> >
>> >> >
>> >> >
>> >> >
>> >> > --
>> >> > Daniel C. Sobral
>> >> >
>> >> > I travel to the future all the time.
>> >> >
>> >
>> >
>> >
>> > --
>> > Daniel C. Sobral
>> >
>> > I travel to the future all the time.
>> >
>
>
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

Well, you can type the name of the class on the search box too.

On Tue, Mar 2, 2010 at 8:24 PM, Cay Horstmann <cay.horstmann@gmail.com> wrote:

That only works for the IMMEDIATE superclass.

On Tue, Mar 2, 2010 at 1:29 PM, Daniel Sobral <dcsobral@gmail.com> wrote:
> You go to collection.IndexedSeqLike by clicking on its link, which is shown
> right below the class name, at the top of the doc.
>
> On Tue, Mar 2, 2010 at 5:06 PM, Cay Horstmann <cay.horstmann@gmail.com>
> wrote:
>>
>> We have now come full circle.
>>
>> Sure, all I have to do is go to collection.IndexedSeqLike.
>>
>> I would love to have an easy way to go to collection.indexedSeqLike.
>>
>> But how do I do that?
>>
>> Not by clicking on IndexedSeqLike. That does something that you all
>> agree is rarely useful in practice, namely to hide exactly the methods
>> provided by that type.
>>
>> My original request was to make the supertypes clickable links that
>> let you go to those types.
>>
>> If there really is a use case for fine-grained showing/hiding by
>> supertype (and I agree that this is really more for someone idly
>> perusing Scala APIs), then provide that with checkboxes.
>>
>> I don't think I am asking for something bizarre here. The original
>> Scaladoc (as well as Javadoc) have an easy way of getting at the
>> supertypes, and there is no reason that this functionality should be
>> taken away in scaladoc2, merely to have a feature for idle API
>> browsers.
>>
>> Cheers,
>>
>> Cay
>>
>> On Mon, Mar 1, 2010 at 7:38 AM, Daniel Sobral <dcsobral@gmail.com> wrote:
>> > mutable.IndexedSeqLike inherits all methods in
>> > collection.IndexedSeqLike. So
>> > all you have to do is go to collection.IndexedSeqLike. And, if you want
>> > just
>> > the methods _defined_ at collection.IndexedSeqLike, click on Hide All.
>> > But Christopher has the right of it here. When you consider
>> > mutable.IndexedSeqLike, you are interested in what _it_ provides. If,
>> > for
>> > any method, you wonder what its descendency is, you just click on it and
>> > see
>> > its "definition classes".
>> > The usage you describe is really more one of someone idly perusing Scala
>> > APIs than one that of someone writing code and needing help. Not that
>> > there's anything wrong with the former, but the new scaladoc is focused
>> > on
>> > the latter. It might help pointing that out. :-)
>> >
>> > On Mon, Mar 1, 2010 at 1:12 AM, Cay Horstmann <cay.horstmann@gmail.com>
>> > wrote:
>> >>
>> >> Ok, that's fine. In effect, it is the first group in the "grouped by
>> >> supertypes" list that I suggest.
>> >>
>> >> How would you obtain all methods that mutable.IndexedSeqLike inherits
>> >> from collection.IndexedSeqLike? With scaladoc2 you have to
>> >>
>> >> 1) Click "Hide All"
>> >> 2) Click IndexedSeqLike
>> >>
>> >> Anyway, that really helps me out with my original problem--how not to
>> >> lose face in my presentation. I'll explain that "Hide All" is your
>> >> friend.
>> >>
>> >> Thanks,
>> >>
>> >> Cay
>> >>
>> >>
>> >>
>> >> On Sun, Feb 28, 2010 at 5:04 PM, Daniel Sobral <dcsobral@gmail.com>
>> >> wrote:
>> >> > The way I'd compare mutable.IndexedSeqLike with
>> >> > collection.IndexedSeqLike is
>> >> > to go to the former and hide all inherited methods. What's left is
>> >> > what
>> >> > is
>> >> > what mutable.IndexedSeqLike overrides or introduces,  Expanding them,
>> >> > one
>> >> > can see the definition classes for any method that is overridden.
>> >> > It works for me. What are your issues with it?
>> >> >
>> >> > On Sun, Feb 28, 2010 at 11:25 AM, Cay Horstmann
>> >> > <cay.horstmann@gmail.com>
>> >> > wrote:
>> >> >>
>> >> >> I do realize that, yes. But look at ArrayBuffer.
>> >> >>
>> >> >> class   ArrayBuffer[A] extends Buffer[A] with
>> >> >> GenericTraversableTemplate[A, ArrayBuffer[A][A]] with BufferLike[A,
>> >> >> ArrayBuffer[A]] with IndexedSeqLike[A, ArrayBuffer[A]] with
>> >> >> Builder[A,
>> >> >> ArrayBuffer[A]] with ResizableArray[A]
>> >> >>
>> >> >> There are 6 direct supertypes (clickable) and 31 supertypes in the
>> >> >> "Inherits" list that are not clickable.
>> >> >>
>> >> >> How is someone who isn't intimately familiar with the internals of
>> >> >> the
>> >> >> collections hierarchy going to know what to hide or show if you
>> >> >> don't
>> >> >> let them discover it?
>> >> >>
>> >> >> In particular, when you pairs of indistinguishable "IndexedSeq
>> >> >> IndexedSeq", "IndexedSeqLike IndexedSeqLike", "Seq Seq", and
>> >> >> "Iterable
>> >> >> Iterable".
>> >> >>
>> >> >> This brings up another problem with the Show/Hide concept. Look at
>> >> >> scala.collection.mutable.IndexedSeqLike. Let's say I want to know
>> >> >> how
>> >> >> it differs from scala.collection.IndexedSeqLike.
>> >> >>
>> >> >> Here is the process:
>> >> >> - Go to scala.collection.mutable.IndexedSeqLike
>> >> >> - Scroll through all methods. On my screen, there are 8 pages of
>> >> >> them.
>> >> >> - Use your photographic memory to memorize all of them
>> >> >> - Click the IndexedSeqLike button to hide them
>> >> >> - Scroll through all methods. On my screen, there are now 7 pages of
>> >> >> them.
>> >> >> - Use your photographic memory to determine the difference
>> >> >>
>> >> >> Or am I missing something here?
>> >> >>
>> >> >> If not, the Show/Hide mechanism seems pretty worthless. It would be
>> >> >> more useful to  have a toggle that switches between alpha order and
>> >> >> a
>> >> >> listing that is grouped by the supertypes.
>> >> >>
>> >> >> Cheers,
>> >> >>
>> >> >> Cay
>> >> >>
>> >> >>
>> >> >>
>> >> >>
>> >> >>
>> >> >> On Sat, Feb 27, 2010 at 6:22 AM, Daniel Sobral <dcsobral@gmail.com>
>> >> >> wrote:
>> >> >> > You do realize you can click on the supertypes mentioned in the
>> >> >> > declaration
>> >> >> > itself, right below the class name, don't you?
>> >> >> >
>> >> >> > I'll beg to differ regarding the class toggling, though your
>> >> >> > suggestion
>> >> >> > has
>> >> >> > merit.
>> >> >> >
>> >> >> > On Fri, Feb 26, 2010 at 7:47 PM, Cay Horstmann
>> >> >> > <cay.horstmann@gmail.com>
>> >> >> > wrote:
>> >> >> >>
>> >> >> >> I am putting this on scala-internals because I was previously
>> >> >> >> admonished not to put scaladoc2 issues on scala-user.
>> >> >> >>
>> >> >> >> I am preparing a workshop for CS instructors interested in using
>> >> >> >> Scala
>> >> >> >> for college courses. I am boldly using 2.8, which means
>> >> >> >> scaladoc2.
>> >> >> >> And
>> >> >> >> here is my problem. I want to go over some basic collections,
>> >> >> >> such
>> >> >> >> as
>> >> >> >> ArrayBuffer. But I can't figure out how to show the scaladoc2
>> >> >> >> page
>> >> >> >> without losing face.
>> >> >> >>
>> >> >> >> People will want to know the supertypes and their purpose. They
>> >> >> >> will
>> >> >> >> want to *navigate* to them. That's much more important than the
>> >> >> >> hide/show behavior which is pretty worthless for a class with
>> >> >> >> many
>> >> >> >> members and many supertypes (such as ArrayBuffer).
>> >> >> >>
>> >> >> >> ArrayBuffer is particularly embarrassing because it has two
>> >> >> >> supertypes
>> >> >> >> Seq that appear indistinguishable. There is simply no way of
>> >> >> >> finding
>> >> >> >> out what each of them is in the ArrayBuffer scaladoc2 page.
>> >> >> >>
>> >> >> >> So, here is my constructive suggestion.
>> >> >> >>
>> >> >> >> In the list of supertypes, make each type act like any other
>> >> >> >> clickable
>> >> >> >> type, i.e. on mouse over show the package name and on click
>> >> >> >> follow
>> >> >> >> the
>> >> >> >> link to the type's page. AFTER each of the supertypes, put a
>> >> >> >> checkbox
>> >> >> >> (or some other doohickey if you dislike checkboxes) to toggle the
>> >> >> >> show/hide status. Yes, it takes a small amount of additional real
>> >> >> >> estate, but it will be a HUGE improvement for usability.
>> >> >> >>
>> >> >> >> Thanks,
>> >> >> >>
>> >> >> >> Cay
>> >> >> >
>> >> >> >
>> >> >> >
>> >> >> > --
>> >> >> > Daniel C. Sobral
>> >> >> >
>> >> >> > I travel to the future all the time.
>> >> >> >
>> >> >
>> >> >
>> >> >
>> >> > --
>> >> > Daniel C. Sobral
>> >> >
>> >> > I travel to the future all the time.
>> >> >
>> >
>> >
>> >
>> > --
>> > Daniel C. Sobral
>> >
>> > I travel to the future all the time.
>> >
>
>
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

--
Daniel C. Sobral

I travel to the future all the time.

Sure, and I have done so many more times than I wanted to. Not only is
it annoying to retype the name, but it is also more work to open it in
a new tab. With a clickable link, I can easily right-click and open in
a new tab.

On Tue, Mar 2, 2010 at 4:30 PM, Daniel Sobral wrote:
> Well, you can type the name of the class on the search box too.
>
> On Tue, Mar 2, 2010 at 8:24 PM, Cay Horstmann
> wrote:
>>
>> That only works for the IMMEDIATE superclass.
>>
>> On Tue, Mar 2, 2010 at 1:29 PM, Daniel Sobral wrote:
>> > You go to collection.IndexedSeqLike by clicking on its link, which is
>> > shown
>> > right below the class name, at the top of the doc.
>> >

Hello.

As Daniel rightly pointed out, Scaladoc 2 currently offers the same links to ancestors as the original Scaladoc.

As Daniel equally rightly pointed out, the inheritance list of Scaladoc 2 improved over the original Scaladoc in that it gives an idea what entities to search for to explore the ancestor hierarchy of a class, something that was difficult in the original Scaladoc.

I understand Cay's frustration in seeing an inheritance list without being able to navigate to its elements. This will come eventually: it had always been my plan to make the inheritance list more flexible so that it can be used for navigation. Because of limited time, however, it hasn't been done yet. This feature had been listed in the to-do list for Scaladoc under the rather inconspicuous title of: “Traits and classes in ancestors list have icons”. I changed it to be more explicit.

https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Todo

> Sure, and I have done so many more times than I wanted to. Not only is
> it annoying to retype the name, but it is also more work to open it in
> a new tab. With a clickable link, I can easily right-click and open in
> a new tab.

You can also right-click on an entity in the left list to open it in a new tab (at least in Safari).

>> Well, you can type the name of the class on the search box too.
>>
>>> That only works for the IMMEDIATE superclass.
>>>
>>>> You go to collection.IndexedSeqLike by clicking on its link, which is
>>>> shown right below the class name, at the top of the doc.

As always, let me remind you of the link to the “contribute” page for Scaladoc 2:

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

Cheers,
Gilles.

Thanks for the links and the heads up! I look forward to having
navigation in that list.

Cheers,

Cay

On Wed, Mar 3, 2010 at 3:12 AM, Gilles Dubochet wrote:
> Hello.
>
> As Daniel rightly pointed out, Scaladoc 2 currently offers the same links to ancestors as the original Scaladoc.
>
> As Daniel equally rightly pointed out, the inheritance list of Scaladoc 2 improved over the original Scaladoc in that it gives an idea what entities to search for to explore the ancestor hierarchy of a class, something that was difficult in the original Scaladoc.
>
> I understand Cay's frustration in seeing an inheritance list without being able to navigate to its elements. This will come eventually: it had always been my plan to make the inheritance list more flexible so that it can be used for navigation. Because of limited time, however, it hasn't been done yet. This feature had been listed in the to-do list for Scaladoc under the rather inconspicuous title of: “Traits and classes in ancestors list have icons”. I changed it to be more explicit.
>
> https://lampsvn.epfl.ch/trac/scala/wiki/Scaladoc/Todo
>