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
