Worst Phobos documentation evar!

[Adam D. Ruppe via Digitalmars-d]

So what's nice about ddoc is it understands the language. I think 
it should know scoping too.

Let's forget about the syntax for a moment and think of a feature 
I'd really like: automatic linkability to mentioned symbols.


module ddoc_test;
import module_with_baz;

void bar() {}

/// See also: $(DSYMBOL bar), $(DSYMBOL baz)
void foo() {}


I think it'd be great if it could recognize bar in there as a 
symbol and actually look it up in the current scope. Then you can 
define a macro to link it.

So it would translate it to $(DSYMBOL ddoc_test.bar bar) and 
$(DSYMBOL module_with_baz.baz baz) and the rest of the code is 
responsible for figuring out how to actually link to it.

The first argument it translates is the fully-qualified name 
determined by scope lookup rules. The second argument is what the 
user actually typed in there.


This would use the fact that ddoc is in the compiler to provide 
something compelling that is hard to do in an external program. 
Changing syntax is easy - dmd -D -X makes the json file which you 
can parse and make your own doc displayer. Getting scope names is 
hard though.