Cross-references in generated ddoc

[Jonathan M Davis]

On Wednesday, April 04, 2012 22:15:10 Ary Manzana wrote:
> But when Walter and Andrei generate the docs they use this:
> 
> https://github.com/D-Programming-Language/d-programming-language.org/blob/ma
> ster/std.ddoc#L316
> 
> If you ask me, that's a bad smell. What if I want to make the docs in my
> own format? How can I know all the macros to use? Hmmm....

ddoc is designed with the idea that you can provide a file with your own macros 
rather than just having built-in ones (not to mention, then having to build in 
all macros into the compiler). It would be incredibly limiting. If you want to 
generate the docs in your own format, then you can provide your own ddoc file 
which defines the macros how you'd like, but it's very much on purpose that 
there be a ddoc file. If you had your own project with macros that helped you 
with your documentation, then anyone wanting to generate the documentation 
differently is going to need to have their own ddoc file with different versions 
of those macros. That's expecteed, and I don't see why it would be a code 
smell. Anything else would be saying that the very idea of user-defined macros 
is a bad idea, which very much goes against how ddoc works.

- Jonathan M Davis