Ability to search jsdoc page for classes

[dchambers]

Now that the jsdoc page no longer uses a tree, this makes class discovery more difficult in the case where the developer doesn't know the name of the class they are looking for. There are two ways of dealing with this problem:

1. Provide nice overview package-level documentation that points out all of the noteworthy classes and interfaces for each library being documented, and use this to find your way around.
2. Provide a browsing mechanism that allows developers to limit what they look at to a single package at a time.

I suspect the first option is probably the most useful, since packages aren't really designed as a discovery mechanism, but having a solution for the second option could be useful too.

[dchambers]

Since I and others feel that using a package-based tree instead of a flat list of classes and interfaces creates as many problems as it solves, I'd like to propose the following search based solution to item 2 above:

1. Show everything in the index by default.
2. Have a combo-box where you can type package prefixes to limit what is shown in the index (e.g. br/presenter or acme.grid), where the combo-box is pre-populated with the list of all possible package prefixes so the user can auto-complete rather than typing in full.
3. Store the user's package filter within session-storage so that their filter will continue to apply within the page where they performed the filter, but will not be re-created in new tabs or browser windows.
4. Provide a 'cross' button that allows the package prefix to be cleared without having to type an empty string.
5. Ideally allow package prefixes to be typed from the middle (e.g. control rather than br/presenter/control).
6. Do all of this in client-side JavaScript so that the pages we deliver to the client can remain nice and simple for search engines, and so we don't have to heavily customize the default 'jsdoc3' templates.

[dchambers]

@fauna5 & @bit-shifter: what do you think about this proposal?

[leggetter]

For our docs we use Google Custom search:

• Search input: https://github.com/BladeRunnerJS/brjs-site/blob/gh-pages/_layouts/docs.html#L25-L28
• Results: https://github.com/BladeRunnerJS/brjs-site/blob/gh-pages/docs/search.html

It's purely JavaScript-based so we could use that? It could then also integrate content from other sources such as the docs on the main site. See:
http://bladerunnerjs.org/docs/search/?s=blades

There's probably a way to make the first tab only show API Docs and another tab showing results from elsewhere.

[dchambers]

Hi @leggetter, this proposal isn't for document search, but instead describes a mechanism to limit what's shown in the index pane without using a tree, as is normally done for API docs.

[andy-berry-dev]

@dchambers is this now done and ready for test?

[thecapdan]

This is done and works as expected in chrome and firefox.

A couple of minor problems with IE:

1. All IE - hitting enter after entering a package name does nothing
2. IE9 and below - "placeholder text" does not work, so we get no indication of what to type in the box

These are super low priority - anyone think these are worth fixing given that they only appear in IE?

[thecapdan]

Dom is about to checkin a fix for the second issue mentioned above.

[thecapdan]

Issue 2 fixed by #978

[dchambers]

@thecapdan: The placeholder bug is fixed by #978.

[dchambers]

@thecapdan I've updated #978 to use a new placeholder shim that doesn't break the 'cross' button, and which has zero dependencies.

[thecapdan]

Thanks. Tested - placeholder text now appears in IE9.

There's a super minor issue where the plaeholder text does not appear until you click away. But for the purposes of this issue we can consider it done