ScalaDoc discoverability

On Wed, Dec 28, 2011 at 6:12 AM, Paul Butcher <paul@paulbutcher.com> wrote:

I've just stumbled across Daniel Sobral's excellent guide to using ScalaDoc:

http://dcsobral.blogspot.com/2011/12/using-scala-api-documentation.html

It came as a complete revelation to me that there's an index of methods built-in to ScalaDoc - this would have made my life *dramatically* simpler over the last couple of years had I known about it.

I had never clicked on the method index links because I assumed that they were going to restrict the list of classes to those starting with a particular letter. This may be foolish, but I suspect (actually, I know) that I'm not the only one to make this mistake. They lie underneath a search box that only operates on classes, and it's not unreasonable, therefore, to assume that the same will be true of these links.

Is there anything that we can do to make this more discoverable? Daniel's article is great, but the vast majority of people coming to Scala will be trying to work this out for themselves without its assistance. If we can find a way to make it more obvious to them, it will be a huge help, I suspect...

I too have always made the same incorrect assumption until just now. The fact that the method names themselves are not searchable, but require you to scroll through the list, is pretty inconsistent with how the rest of the UI works.  Kris

IIRC, this index list was the first major contribution of pfurla. I had never thought of this index as you two have, but, then again, I have known it since before it was even available, so to speak. :-) Now that you two have mentioned it, I can see that yours would be the natural assumption. On the other hand, it shows how important my advice to just click on stuff is. :-)
Back to the problem, yes, a search box is missing on the method list, and it shouldn't be too hard to do, though, if I understand correctly, these search boxes use a lot of memory on the client/javascript side to keep things fast. I worry that this might come to bite us, even though the average *developer* machine ought to handle it easily. Someone just remarked on the blog that Scaladoc doesn't work on the iPad, and, sadly, that's true. The right frame doesn't scroll for some reason, and even typing stuff on that search box seems to tax the iPad heavily. The left frame, however, works fine, which is curious.
As for making the index list more discoverable, well... if you have any ideas, please make them! :-) This truly is one place where just an idea of what someone else could implement would be handy. :-) Though I just had one, actually.... mmmm....

On Wed, Dec 28, 2011 at 13:25, Kris Nuttycombe <kris.nuttycombe@gmail.com> wrote:

On Wed, Dec 28, 2011 at 6:12 AM, Paul Butcher <paul@paulbutcher.com> wrote:

I've just stumbled across Daniel Sobral's excellent guide to using ScalaDoc:

http://dcsobral.blogspot.com/2011/12/using-scala-api-documentation.html

It came as a complete revelation to me that there's an index of methods built-in to ScalaDoc - this would have made my life *dramatically* simpler over the last couple of years had I known about it.

I had never clicked on the method index links because I assumed that they were going to restrict the list of classes to those starting with a particular letter. This may be foolish, but I suspect (actually, I know) that I'm not the only one to make this mistake. They lie underneath a search box that only operates on classes, and it's not unreasonable, therefore, to assume that the same will be true of these links.

Is there anything that we can do to make this more discoverable? Daniel's article is great, but the vast majority of people coming to Scala will be trying to work this out for themselves without its assistance. If we can find a way to make it more obvious to them, it will be a huge help, I suspect...

I too have always made the same incorrect assumption until just now. The fact that the method names themselves are not searchable, but require you to scroll through the list, is pretty inconsistent with how the rest of the UI works.  Kris

--
Daniel C. Sobral

I travel to the future all the time.

On 28 Dec 2011, at 21:06, Daniel Sobral wrote:
> As for making the index list more discoverable, well... if you have any ideas, please make them! :-) This truly is one place where just an idea of what someone else could implement would be handy. :-) Though I just had one, actually.... mmmm....

The best solution by a mile, I think, would be to make classes and methods behave the same way - have an index for classes and have a search for methods. That could be exposed either as a couple of search-box-and-index-links pairs, or as a single search-box-and-index-links pair, plus a means of deciding whether it should operate on classes or methods.

Of course, whether that's do-able, I have no idea...

--
paul.butcher->msgCount++

Snetterton, Castle Combe, Cadwell Park...
Who says I have a one track mind?

http://www.paulbutcher.com/
LinkedIn: http://www.linkedin.com/in/paulbutcher
MSN: paul@paulbutcher.com
AIM: paulrabutcher
Skype: paulrabutcher