- About Scala
- In the Enterprise
- Scala Community
- Language Research
- In the Press
- The Scala Team
- Scala's Prehistory
- Contact Us
- Learning Scala
- Tour of Scala
- Scala API
- Setup & Getting Started
- Programming Guides
- Other Guides
- Code Examples
- Scala Developers
A criticism of ScalaDoc output
Mon, 2010-09-27, 13:29
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
and another one (see below), among more
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
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:
(and some other declarations)
They can be restored by adding:
- 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
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.