Re: Online nightly scala-docs...

[moved from scala-users]

Hello.

I agree that the documentation of class MetaData is less practical in Scaladoc 2, in its current state, than it was in Scaladoc 1. As you mentioned, the reason is that MetaData extends a collection class, which provides so many members that MetaData's own members are hard to find. Since MetaData locally implements or overrides all important members, they are shown first in Scaladoc 1.

This isn't the case for other classes. For example, the new collection library (and most other mixin-based libraries) is very poorly documented using Scaladoc 1: most interesting members are inherited and implemented members tend to be relatively trivial. Considering the importance of the collection library, we need Scaladoc to behave in a way that suits it.

I think that your idea of providing a list of members inherited from each super type could be useful. I have already planned — it's in Scaladoc's todo list — to print from where each member is inherited. I don't think that filtering out all inherited members by default is the right behaviour (because of the collection library). Instead, I am thinking of maybe adding an additional documentation tag that controls what inherited members are shown on a class-by-class basis. Also, I am still not sure how the inheritance-visibility buttons should behave: currently, each behaves as a separate toggle button, which implies a lot of clicking in some cases. Another approach that I consider is to have it behave more like a slider: click a class to hide it and all classes later in the linearization are hidden, click a class to show it and all before are shown.

In any case, thanks for pointing out the problem with MetaData, that kind of information is very useful.

Cheers,
Gilles.

Cay Horstmann said:
> Well, actually, if I click on Iterable, it doesn't remove any entries.
> I have to click on ALL buttons--that's a lot of buttons. And when I
> do, I still see overriding members. That isn't wrong--but I have no
> idea what they override.
>
> The old version
> (http://www.scala-lang.org/docu/files/api/scala/xml/MetaData.html) is
> better in two ways.
> (a) It shows the most important methods first
> (b) It shows where all those other methods come from
>
> To achieve this effect with the new design, perhaps the default should
> be (a) to filter out all supertypes, and (b) instead of arranging the
> supertypes in a linear sequence, list them vertically, and next to
> each place a list of the methods that one would see if one unfiltered
> them.
>
> Daniel Sobral said:
>> You can actually remove all supertypes, as they are basically a consequence
>> of Metadata extending Iterable. The supertypes are provided in linearization
>> order, so everything right and down of "Iterable" (ie, everything) can be
>> deactivated.
>>
>> After all, something specific to Metadata isn't going to be found on stuff
>> related to its iterability.
>>
>> This is even a bit related to the present thread on xml and internals, about
>> reworking class inheritance of XML. Having Metadata *be* an iterable and an
>> element at the same time, instead of being an element of an iterable or an
>> iterable of metadata values, sucks.
>>
>> But, alas, this isn't all that different from what we had before, except
>> that the inherited members weren't expanded -- which caused trouble when the
>> method you wanted WAS defined in a parent class. There was one suggestion of
>> a search for methods that would bring all classes with that define that
>> method, I think I suggested searching for a method inside a class, and
>> someone else suggested searching for type signatures. None of them seems to
>> help you, except, perhaps, the latter one. If you knew the name, you could
>> just find it with the browser search feature.
>>
>>> Unfortunately, I find it very hard to use the new ScalaDoc.
>>>
>>> Today I need to do some XML handling. I need the attribute map of a
>>> node. Apparently it is a scala.xml.MetaData. Quick, how do I get the
>>> value of the attribute with a given name?
>>>
>>> A flat list of 105 entries (check it out at
>>>
>>> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/...)
>>> is not useful.
>>>
>>> Those supertype buttons aren't effective either. First off, there is a
>>> good chance that the method I am seeking is defined or overridden in
>>> this class, and I would have to laboriously click all buttons to hide
>>> all supertypes. There needs to be a quick way of showing me just the
>>> methods that are implemented in this type.
>>>
>>> Next, I am not familiar with all those traits--I have no information
>>> whether it would be useful to filter out HasNewBuilder, for example.
>>> It would help if that list of supertypes was expanded to include (a)
>>> include a one-line description of the type (b) a list of the names of
>>> the inherited members to give me some idea of the structure.
>>>
>>> Also, what happened to the hyperlinks in type names? I cannot jump to
>>> a related class (e.g. NamespaceBuilder) if I need more information
>>> about it. That is really bad.
>>>
>>> I realize this is a work in progress, and I hope everyone can chime in
>>> with constructive criticism.
>>>
>>>> In fact, it is the future. I strongly recommend evaluating what it
>>>> brings, reading carefully that discussion, particular what has been recognized
>>>> as being a missing feature from the start and what has already been added
>>>> to the missing list, and then speaking your mind about it.
>>>>
>>>> I had a few strong words myself, though I'm not against the project per
>>>> se, or the fact that it had to go "on" at some point. I just hope much
>>>> progress is made before 2.8 is out.