On Sun, Sep 15, 2013 at 11:40:28AM -0700, Jonathan M Davis wrote: > On Sunday, September 15, 2013 11:02:11 Andrei Alexandrescu wrote: > > One obvious drawback of ^F working is that all symbols are there in > > sight. > > I actually consider it a serious drawback when they're _not_ in sight. > The problem that we have is not that all of the symbols are shown as > links but how they're organized. Trying to hide them doesn't help. [...]
+1. What we need is not Yet Another Snake Oil Automagic Trick that will somehow magically make it all work. What we need is to sit down and put in the time to organize the module docs, grouping the symbols by logical categories (which a computer can't really figure out for us, unless we tag the code, which requires the same amount of effort anyway). I think std.algorithm and std.range's docs are a good model to follow. They set the minimum standard all Phobos docs should meet. Of course, we can also improve on them even more, by figuring out a way to prevent the DRY violation currently in std.algorithm (to add a new symbol, you now have to add it in 3 places: at the navigation table at the top, then in the cheatsheet, then the actual code in the module body). Maybe some kind of DDoc tag or UDA that can be collected by a postprocessing script that autogenerates the relevant tables based on what information is there? For example: // Note: not actual syntax, I just made this up for illustration // purposes: /** * @category: searching * @cheatsheet: newHaystack = find(haystack, needle) * * Finds needle in haystack. * ... */ R find(R,S)(R haystack, S needle) { ... } The postprocessing tool would then collect all the @category tags and @cheatsheet tags and assemble a table out of them, linked to the relevant symbols, and insert it at the top of the page. (Or, it could even split the files up into individual pages, which we've been talking about since, oh, last year?) T -- I think the conspiracy theorists are out to get us...