Cross referencing in Ddoc

Jacob Carlborg doob at me.com
Sun Dec 29 09:38:55 PST 2013


If nothing has happened recently the current situation of cross 
referencing in Ddoc sucks. What's currently being used in the Phobos 
documentation is the XREF, CXREF and ECXREF ddoc macros. These macros 
take two arguments, append "std", "core" or "etc" and form a link of the 
arguments. The problem with this is that it doesn't work so good for 
referring to symbols in a deeper package hierarchy.

Example, adding a reference to std.path.buildPath works fine but symbols 
that are any deeper than that will not work very well, like 
std.digest.digest.toHexString.

$(XREF path, buildPath)

The above will generate a link to std_path.html#buildPath with the text 
"std.path.buildPath". If we want to create a link to 
std.digest.digest.toHexString we get in to some problems, XREF doesn't 
accept a variable amount of arguments, the following will not work:

$(XREF digest, digest, toHexString)

What will work is this:

$(XREF digest_digest, toHexString)

The above will properly create a link to 
std_digest_digest.html#toHexString but that relies on the fact that DMD 
replaces dots with underscores in module names when generating 
documentation. But the text of the link will be 
"std.digest_digest.toHexString" which doesn't look very pretty.

The XREF macro also hard codes the root package, making it only work for 
"std".

I think we need a better solution for creating cross referencing links 
in ddoc. Here are a couple of ideas:

A. Automatic cross reference

Automatically create links for all matching symbols in the current 
scope. That means to create a link to a symbol in the current scope it's 
enough to mention it's name in the documentation. To refer to a symbol 
in another module the fully qualified name is used. Examples:

"Read and validates (using $(XREF utf, validate)) a text file."

Would become:

"Read and validates std.utf.validate a text file."

And

"The default $(XREF _algorithm, move) performs a potentially"

Would become:

"The default move performs a potentially"

Advantages:

* Everything happens automatically, the developer doesn't have to do 
anything special to add cross referencing

Disadvantages:

* It might create links where it's not wanted
* Requires support from the compiler

B. REF macro

A special macro that the compiler knows about. Pass the symbol name 
(local or fully qualified) to the macro and the compiler will generate 
the link. Examples:

"Read and validates (using $(XREF utf, validate)) a text file."

Would become:

"Read and validates $(REF std.utf.validate) a text file."

And

"The default $(XREF _algorithm, move) performs a potentially"

Would become:

"The default $(REF move) performs a potentially"

Advantages:

* No links are created where it's not wanted

Disadvantages:

* The developer need to manually add macros, still better than today though
* Requires support from the compiler

C. A combination of A and B

By default ddoc behaves as option B, but in See_Also sections ddoc 
behaves as option A.

Advantages:

* No links are created where it's not wanted

Disadvantages:

* The developer need to manually add macros but hopefully not in as many 
places as with option B
* Requires support from the compiler

What do you think?

-- 
/Jacob Carlborg


More information about the Digitalmars-d mailing list