Improved Phobos dox

[Vladimir Panteleev]

On Sunday, 15 September 2013 at 18:02:10 UTC, Andrei Alexandrescu 
wrote:
> Vladimir, do you think you could easily implement such an 
> incremental search box (with autocompletion)?

Sorry, that idea does not appeal to me either. Web browsers 
already have the function of searching within a page. An in-page 
search box is not a common UI element, users would need to learn 
to use it, and that's bad UX - we should stick to existing UI 
conventions to avoid forcing the users to think to get to their 
dox.

I think an index like the one std.algorithm has, and that ddox 
attempts to generate automatically, is really the best solution 
from all sides. It provides a birds-eye view of the whole module 
useful to new users; it allows quickly finding the sought 
function through its table layout and categorization; and, the 
first Ctrl+F hit for a symbol name will likely be a link to the 
symbol, with a short synopsis nearby it. It's pretty hard to beat.

I think this is the direction we need, and that it's not worth 
considerably changing things with interim solutions (which will 
impact D users who consult the documentation often) that are more 
of a trade-off rather than an improvement.

Implementation-wise:

I assume Ddox has failed to be integrated because it was a 
server-side process. It also places each symbol in its own file, 
which will break existing links. Perhaps it be feasible to 
reimplement only its basic index-table functionality in 
JavaScript, to replace the word-blob/dropdown?

Symbol documentation could contain macros which render to 
invisible HTML, which is picked up by the index-table JS for 
metadata like categorization.