DDoc with cross-references

[Jonathan M Davis]

On Monday, April 02, 2012 13:52:47 Ary Manzana wrote:
> 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)?

I'm not arguing it one way or another. I'm just pointing out how it works now.

> > 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.

The anchors have been a big problem for a long time. A prime example of where 
they're horrible is std.datetime. They maintain _no_ hierarchy whatsoever. So, 
_everything_ gets lumped together as it were a free function, and if anything 
has the same name (e.g. DateTime and SysTime both have a year property), then 
they end up with identical anchors. The result is that the links at the top of 
std.datetime are nearly useless.

It's ddoc's biggest problem IMHO.

- Jonathan M Davis