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