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.
