Improved Phobos dox

[Jacob Carlborg]

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