On 2013-09-16 06:50, H. S. Teoh wrote:
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?)
I think we should try and enhance the documentation generated automatically. Tagging and doing other things manually doesn't scale. This should only be used as a last option.
-- /Jacob Carlborg
