DDoc with cross-references

[Ary Manzana]

On 4/2/12 12:39 PM, Jonathan M Davis wrote:
> On Monday, April 02, 2012 12:20:31 Ary Manzana wrote:
>> I'm planning to add cross-references to the default ddoc output. At
>> least that's the simplest thing I could do right now that might improve
>> ddoc somehow.
>>
>> I see the documentation generated for phobos, for example:
>>
>> http://dlang.org/phobos/std_array.html#Appender
>>
>> has anchors to the many symbols (in fact, now I notice it's flawed,
>> because they are not fully-qualified).
>>
>> Does anyone know where can I get the macros for generating such output?
>> I will need it for generating the cross-links.
>>
>> But a more appropriate question is: why the default ddoc output doesn't
>> generate such anchors by default? At least putting an ID to the
>> generated DT...
>
> Phobos' macros are in
>
> https://github.com/D-Programming-Language/d-programming-
> language.org/blob/master/std.ddoc
>
> As for linking macros,
>
> LREF is used for references within a module.
> XREF is used for references to std modules.
> CXREF is used for references to core modules.
> ECXREF is used for references to etc.c modules.

Again, the same things. D has ddoc and it tries to do everything with 
ddoc. No, that's plain wrong. Links to other module members should be 
done automatically. And the links should come from the compiler. The 
compiler has that knowledge already, why loose it and work on a less 
powerful level (ddoc)?

>
> As for Appender, I don't see any links at all, so I don't know what you're
> talking about. The generic D macro (which just designates D code) is used by
> it in some places, and ddoc does put some stuff in italics in some cases (e.g.
> the name of a function's parameter in the documentation for that function),
> but there are no links in Appender's documentation.

What I meant is, every member in the module has an anchor. In the case 
of Appender it looks like this in the generated HTML:

<a name="Appender"></a>

That's why I can give you this link:

http://dlang.org/phobos/std_array.html#Appender

and it scrolls down to Appender (I know you know it already, but it 
seems I wasn't clear in my previous post).

Now, that is flawed because the name is not fully qualified. And there's 
no macro to get a fully qualified name or link to other members modules.