Improved Phobos dox

[H. S. Teoh]

On Mon, Sep 16, 2013 at 08:58:31AM +0200, Jacob Carlborg wrote:
> 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.
[...]

The problem is that Walter wants DDOC to be a generic macro-expansion
system. Adding any further smarts to it would tie it down to D-specific
functionality, which reduces the likelihood of it being accepted.

But, you may be able to change his mind. :)


T

-- 
Computers are like a jungle: they have monitor lizards, rams, mice,
c-moss, binary trees... and bugs.