This page is no longer maintained — Please continue to the home page at www.scala-lang.org

New Scaladoc suggestions

3 replies
David Hall 4
Joined: 2009-08-21,
User offline. Last seen 42 years 45 weeks ago.

Hi all,

I know it's work in progress, and I think that there are some very
good ideas here, but the current interface has a couple of issues for
me:

1) No link to the source. This is hugely important for me. I basically
find myself browsing the source through trac instead.
2) the "growing links" for superclasses and traits, while cool, don't
work always (for me in Google Chrome), because the growth occasionally
causes some of the text to wrap, and it ends up I can't click on the
link. This happens for me in ArrayBuffer.
3) I like the ability to hide methods associated with classes, but can
there also be a hide-all button, and then I can add back in the ones I
want?
4) The ? and target mouse pointers are really... disturbing. Can they
just be the little mouse-over-link hand? Please?

Thanks,
David

ichoran
Joined: 2009-08-14,
User offline. Last seen 2 years 3 weeks ago.
Re: New Scaladoc suggestions
I'm afraid I don't like the new scaladoc much.  It _could_ be an improvement, but right now I find that it takes quite a bit longer to find the information I'm looking for.

Major issues I have are:

(1) The standard Javadoc format allows you to see everything within a package without having to wade through everything in parent packages (in the left sidebar).  Scaladoc no longer does--so I'm forced, for example, to have 100-odd lines of the Scala base classes at the top of the list of classes I'm actually looking for, or to jump back and forth between the full-window description of the packages and of classes etc. contained therein.

(2) Bright blue on white is much more attention-grabbing than dim blue on gray, and table boxes are much clearer groupings than gray-with-white-below (as opposed to gray-with-white-above).  Thus, when trying to understand what methods a class has, the old Javadocs are visually much clearer.

(3) The hidden long description of methods is cool for looking up what an individual method does (better than Javadoc) but uncool for comparing multiple methods in depth--lots of clicking and text jumping around to be able to see what you need to.

(4) Jumping types (long form on mouseover) are occasionally handy, but mostly just make it difficult to aim at what you want if you're traveling with your pointer down the line.  One can learn to always go from above or below, but it's a pain.

(5) Types are no longer visually distinct from argument names.  Javadoc again wins--if you want to know types, look for blue.  If you want to know parameter names, look for bold black.

(6) It's really nice to be able to look at all methods in addition to presently-defined methods.  But it's really un-nice to not know where the methods came from without clicking through to the entire superclass hierarchy and then trying to remember which ones you were looking for.  This is important when you're trying to decide how far up the hierarchy you should go when extending a class.  (Easy solution: have a button to turn self-defined stuff off.  Then you can see only that inherited stuff that you want to see.)

(7) The hierarchy is easily and immediately visible with the click in-and-out buttons for showing whether methods are inherited.  But you can only easily move directly to the direct ancestors--you can't click on anything (not anything obvious, anyway) to jump back to a superclass.  For the collections hierarchy, this is a very common thing for me to do.  It is _partly_ compensated for by being able to show inherited methods, but not entirely.

(8) Why are packages at the bottom of the Type hierarchy?  When I'm looking at scala.collection, I probably am not desperate to know that trait BitSet extends Set[Int] with BitSetLike[BitSet], but I probably do want to know (if I don't already) that the subpackages are generic, immutable, interfaces, mutable, and script.

(9) All the fancy JavaScript breaks cutting and pasting in many cases.  (Suppose you want to tell someone that trait BitSet extends Set[Int] with BitSetLike[BitSet]....)

(10) It's slow.  This isn't a huge issue, but you certainly notice when loading scala.collection.script.Script that churning through all that Javascript is not instantaneous.  With the new features you do need to make fewer clicks, which is a win, but I'm not sure that it's not all lost again with the extra load time.  (Maybe we should all be using Google Chrome?)

(11) People coming from Java are used to Javadoc.  This looks alarmingly different.  If it was alarming and universally better, no worries.  Alarmingly different without dramatic improvement (or alarmingly different and worse) is not a good idea when trying to increase adoption.

Anyway, I haven't actually timed the change in productivity with the new docs vs. the old ones, but even given the nice groupings of traits and easy access to companion objects and all, my subjective feeling is that it's slowing me down by a factor of 2-3 (probably closer to 2 as I get used to it).  Since, when coding in Scala, I still often spend a good chunk of my time reading documentation (~20%?), this is a very noticable change.

Am I doing something wrong, or have others also noticed a similar loss of productivity?

  --Rex

P.S. Is there a way to compile the documentation into the old format?

On Wed, Jan 27, 2010 at 1:43 PM, David Hall <dlwh [at] cs [dot] berkeley [dot] edu> wrote:
Hi all,

I know it's work in progress, and I think that there are some very
good ideas here, but the current interface has a couple of issues for
me:

1) No link to the source. This is hugely important for me. I basically
find myself browsing the source through trac instead.
2) the "growing links" for superclasses and traits, while cool, don't
work always (for me in Google Chrome), because the growth occasionally
causes some of the text to wrap, and it ends up I can't click on the
link. This happens for me in ArrayBuffer.
3) I like the ability to hide methods associated with classes, but can
there also be a hide-all button, and then I can add back in the ones I
want?
4) The ? and target mouse pointers are really... disturbing. Can they
just be the little mouse-over-link hand? Please?

Thanks,
David

Mohamed Bana 2
Joined: 2009-10-21,
User offline. Last seen 42 years 45 weeks ago.
Re: New Scaladoc suggestions
Determining where exactly the method in the type hierarchy is highly frustrating, to say the least.  I currently don't like the new approach, I much prefer the javadoc method.
I'm also wondering how Scaladoc2 was designed.  To the best of my knowledge, it just sprang up.  Did anyone elicit requirements?  
I more or less agree with both of the above posts.
—Mohamed
Gilles Dubochet
Joined: 2010-01-28,
User offline. Last seen 42 years 45 weeks ago.
Re: New Scaladoc suggestions

Hello.

I just sent an answer to a similar email on the main Scala mailing list.

Basically, I agree with all the comments you make. Some of your remarks
are already in Scaladoc's Todo list (like the link to source). The
problem is that I just don't have the time to fix everything that needs
to be fixed very quickly. I depend on external contributors to increase
development speed of Scaladoc.

In other words, the only sensible answer I can give to your email is to
forward you the link to this page:

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

Cheers,
Gilles.

> I know it's work in progress, and I think that there are some very
> good ideas here, but the current interface has a couple of issues for
> me:
>
> 1) No link to the source. This is hugely important for me. I basically
> find myself browsing the source through trac instead.
> 2) the "growing links" for superclasses and traits, while cool, don't
> work always (for me in Google Chrome), because the growth occasionally
> causes some of the text to wrap, and it ends up I can't click on the
> link. This happens for me in ArrayBuffer.
> 3) I like the ability to hide methods associated with classes, but can
> there also be a hide-all button, and then I can add back in the ones I
> want?
> 4) The ? and target mouse pointers are really... disturbing. Can they
> just be the little mouse-over-link hand? Please?

Copyright © 2012 École Polytechnique Fédérale de Lausanne (EPFL), Lausanne, Switzerland