A criticism of ScalaDoc output

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

A criticism of ScalaDoc output

Philippe Lhoste
I have seen people complaining about the current state of the ScalaDoc of 2.8.0.
I mean http://www.scala-lang.org/api/current/index.html
As a newbie, I have to refer to it, and found some usability issues.
I thought I should report them, trying to remain in a positive tone: like in most open
source projects, human resources are limited and might have higher priorities. And most of
the things I report there are probably already known.
Warning: this is a rather long mail...

Well, I looked at Trac and found ticket 3402 Overhaul of API Documentation
<http://lampsvn.epfl.ch/trac/scala/ticket/3402> and another one (see below), among more
specialized complaints...
I don't know if I must open one or several Trac tickets...

# One of the first issue is the "accordion" effect I see in the incremental search. If I
type 'Sys' for example (no quotes), it takes some 6s (slow computer, Firefox, Chrome) to
filter out the list.
I use daily the Javadoc Incremental Search user script (Greasemonkey, found at
http://www.teria.com/~koseki/tools/gm/javadoc_isearch/index.html page) which do a similar
thing on any JavaDoc, and the speed is excellent.
I am not the only one to complain, see Increase performance of incremental search
I thought it was because of some jQuery animation but it seems it is a deeper problem.

# Second issue: the idea of hiding information. They had a similar idea for the JavaFX API
documentation, and it was as much ineffective, in an interestingly different way...
When I do a search in Firefox, in the JavaFX doc it can find a hidden item and I don't
know where the selected / found text is. In the ScalaDoc, it doesn't find the text at all,
which isn't better... (I suppose one use display while the other use visible attributes.)
Example: in the List (scala.collection.immutable) page, if I search TraversableOnce, I
find some hits, but not the mention in the expanded doc of min().

Somehow, the good old Web 1.0 style of JavaDoc doesn't fail with that. A suggestion: maybe
do it old style, short descriptions at the top, longer descriptions with code examples and
such at the bottom. And perhaps two buttons: one to jump to the long description old style
(anchor jump), another which would move the long description just below the short one,
restoring it when moving another description.

# Third: there are some errors in the CSS and JS.
I can see some in the Firefox console (it reports CSS errors).

- Incorrect value for border-left-style, line 175 of current/lib/index.css (declaration of
#content, value is "white", so should be "border-left-color" instead).

- Incorrect value for font-style, line 301 of current/lib/template.css (declaration of
.cmt a, value is "bold", so should be "font-weight" instead).

- Both Firefox and Chrome complain that top.loadFrames() seen in
<frameset cols="20%,80%" title="" onLoad="top.loadFrames()">
doesn't exist ("top.loadFrames is not a function", "Uncaught TypeError: Object [object
DOMWindow] has no method 'loadFrames'")

- bold and underline styles are not visible (with a small ScalaDoc test, using '''bold'''
or __underline__). The tags are generated, but a declaration cancels them:

* {
   text-decoration: none;
   font-weight: normal;
(and some other declarations)

They can be restored by adding:

b {
   font-weight: bold;
u {
   text-decoration: underline;

- There is no way to escape markup chars (eg. adding a simple ^ as somebody complained in
the mailing list), except perhaps by surrounding them with backticks, which changes their

- The link to Scala classes like [[scala.collection.Set]] doesn't work (links to sites work).

- When I type a char in the search field, I get a warning: the property "charCode" of a
"keyUp" event should not be used. This value makes no sense. (Translated from French.)

- In the JavaDoc search field added by the GM script mentioned above, typing Excep lists
only the classes / interfaces starting with that. I have to type *Excep to get a list of
the Java exceptions.
I tried that (before seeing that ScalaDoc match anywhere in the name) and it crashed the
JavaScript! I had to reload the page to make the search working again.
I have the error: "invalid quantifier *[a-z]*Prio" on the line:

queryRegExp = new RegExp(query.replace(/([A-Z])/g,"[a-z]*$1"));

I think the script should escape special chars before processing the request... Or at
least surround such line with a try / catch block.

# Lastly, the content can be confusing for a newbie, as I pointed out in a previous
message. Something like the definition of flatMap is very hard to understand for somebody
just seeing this function in a blog article and wanting to look up what it does...
We miss more complete descriptions, and short examples of use, which might be as simple as
List(1, 2, 3).map(n => 2 * n)

I think that's a community task, not obvious because newbies can't really contribute
(except for the simplest things) and experts might have forgotten what was difficult when
reading this doc...

Note: I understood, from a message here, that the [use case] entries are generated with a
special ScalaDoc keyword, precisely to show simpler signatures. That's nice, but their
presentation is confusing, I thought it was just an overloaded version of the more complex
function. They should not appear as two different functions, IMHO.

I hope I wasn't too boring and that my remarks will be useful to whoever maintain these docs.

Philippe Lhoste
--  (near) Paris -- France
--  http://Phi.Lho.free.fr
--  --  --  --  --  --  --  --  --  --  --  --  --  --