Improved Phobos dox

[H. S. Teoh]

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...