Worst Phobos documentation evar!

[Walter Bright via Digitalmars-d]

On 12/29/2014 5:33 PM, Adam D. Ruppe wrote:
> 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.

That's a good idea. How about turning this into an enhancement request in bugzilla?