Scaladoc could use a searchbox that returns results across all packages, classes, searches by type, etc

[scabug]

Quite often when using a library, I will be looking at some sample code that uses the library and will want to look up the definition for some function, foo, but I don't know where foo is defined. Perhaps because foo is a pimped method, or it comes from an import like import blah.Bar._, etc.

In these cases, I have no way of finding the definition of foo. I could randomly look through the api docs in the hopes I find it, but that could take forever. My best bet is to download and grep the source... which is pretty lame.

Scaladoc would be an order of magnitude more useful with a search box where I can find all the instances of foo defined across all modules in the project, presented as a list of search results like a google search - I can then click on the result to go to the detailed docs on it. I think this could even completely replace the existing search panels. I imagine the "scaladoc" being a single text field centered on the page where you can enter search queries. If you just want to list all the classes, for example, perhaps you say "@class". If you want the class named Foo, you do "@class Foo". If you want the method bar you do "@method bar", etc. If you just want to see all "bar" identifiers, regardless of their type, you just do "bar". Etc.

Some other ideas - eventually could add type-based queries. So "foo : Int => Int" finds methods and functions with that signature, "@class Foo: Baz" finds classes named Foo that are considered a subtype of Baz, and so on.

It seems like this is probably all possible with some javascript magic.

[scabug]

Imported From: https://issues.scala-lang.org/browse/SI-4837?orig=1 Reporter: @pchiusano

[scabug]

@heathermiller said: Have you ever tried the alphabetical index under the search bar? (On the left panel) Finding methods is what this index was introduced to do.

To continue with your above example, if you're looking for all possible locations a method foo might be defined, you would simply click the "F" under that search bar, and the right panel will turn to an index of all entities and members beginning with f/F, including methods. You'd simply locate foo in the list, and you'd see all classes/objects/traits which implement foo.

A live example is the method map, defined throughout the standard library. In looking at the scaladoc index page for M, [http://www.scala-lang.org/api/current/index.html#index.index-m], one can see a list of all entities where map is implemented.

Regarding "pimped" methods-- Scaladoc in general doesn't list pimped methods on the class/object/trait they've been pimped onto, yet (expect a solution to this soon). So this is less of a problem with search, and a general soon-to-be-resolved-issue with Scaladoc.

Regarding your other suggestions, such as searching across classes/methods and the type-based queries-- stuff like this would require something like a database, which isn't an option when statically generating documentation to be shipped in the distribution. For that, I'd recommend scalex (or using the search bar on docs.scala-lang.org, which will very very soon return the results of a scalex query on the search results page.)

[scabug]

@heathermiller said: I should mention that once pimped methods are generally available in Scaladoc, they should also show up in the index I just alluded to.

[scabug]

@pchiusano said: I have not used that, that's helpful! It still doesn't provide what I want - how do I find the map function (as opposed to mapConserve, Map2, MultiMap, etc, all of which contain map as a substring)? My browser (Chrome) does not have any options to distinguish among these. Also, it is silly to require two separate steps.

My other suggestions don't necessarily require an external database - if you can generate the index that you are already generating, why not include that same content in javascript literals on the page, and provide a nicer UI to it than just static HTML?

[scabug]

@heathermiller said: The map method is sitting right out in the open on the page I linked to above, I don't see how you could have trouble finding it: !http://f.cl.ly/items/3v0w1p0A181i0j430C1K/Screen%20Shot%202012-03-19%20at%2011.05.03%20PM.png!

Your suggestions do require an external database, for the js filtering to happen in a reasonable time frame. You're asking for all members and entities (and their signatures) of the entire Scala library and peripherals (like the actors library, Scala swing, etc) to be generated (regardless of the format) all on one HTML page and for us to provide a js filter to filter through all of it. That's not feasible or sensible via simple static HTML + js.

A nicer UI than just static HTML? We're likely not going to change the generated format of the doc.

You're essentially asking us to build a completely different Scaladoc. This is not likely.

I remind you to consider comparing the usability of Scaladoc with javadoc.

[scabug]

@heathermiller said: Feature requested already exists. Other suggestions are way out of scope.

[scabug]

@pchiusano said: On my machine, going to that link is just the index of all symbols that begin with m. If I do Ctrl+F and type map, there are 129 matches. If I scroll though enough matches, I can find it, yes. I don't think that's particularly useable.

I don't see this as a completely different scaladoc. The same information gets parsed from the source, you are just generating (different) HTML+Javascript. Maybe you need an external database of some sort for good performance, maybe there are some tricks you can play just with static HTML and javascript to get good performance. (my thought was that the index could be encoded in javascript, and use a technique like http://www.javascriptkit.com/javatutors/loadjavascriptcss.shtml to load the required portion of the index needed for the query).

This was just meant as a suggestion, or more an idea, from someone who uses scaladoc on a regular basis. Yeah, scaladoc is definitely nicer than javadoc. But it could be so much more!