Cross referencing in Ddoc

[H. S. Teoh]

On Sun, Dec 29, 2013 at 06:38:55PM +0100, Jacob Carlborg wrote:
> 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.
[...]

Not only so, even without cross-referencing, the way Ddoc currently does
referencing *within* a module is faulty, because it does not take
symbols declared in nested scopes into account. For example:

	module mymodule;

	/// docs here
	struct S {
		/// docs here
		void func() { ... }
	}

	/// docs here
	void func() { ... }

Ddoc will use "func" as the identifier for *both* mymodule.func and
mymodule.S.func, so any hyperlinks to "func" will likely point to the
wrong overload of func (depending on declaration order).

This problem is actually being exhibited on dlang.org at this very
moment, in std.algorithm. Look for 'remove' in the navigation table at
the top of the page, and click on it; you'll see it jumps to the wrong
place because there's a member function called 'remove' in a struct that
took precedence over the module-level 'remove' function. (Not to mention
it breaks HTML compliance because it gives multiple elements the same
ID.)


T

-- 
People tell me that I'm paranoid, but they're just out to get me.