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

Am 29.12.2013 18:38, schrieb Jacob Carlborg:
> A. Automatic cross reference

This is done for the DDOX based docs that were supposed to end up on the home page at some point:

http://forum.dlang.org/thread/l9poef$210u$1@digitalmars.com http://vibed.org/temp/dlang.org/library/index.html

> * It might create links where it's not wanted

The DDOC specs say that preceding an identifier with an underscore avoids it getting highlighted. DDOX currently uses the same indicator to avoid it getting a link.

See the "Emphasis" section in http://dlang.org/ddoc.html

On 2013-12-29 19:35, Sönke Ludwig wrote:

> This is done for the DDOX based docs that were supposed to end up on the
> home page at some point:
>
> http://forum.dlang.org/thread/l9poef$210u$1@digitalmars.com
> http://vibed.org/temp/dlang.org/library/index.html

Right, forgot about that. When _are_ DDOX becoming the official documentation format. I really don't want to manually add cross referencing.

> The DDOC specs say that preceding an identifier with an underscore
> avoids it getting highlighted. DDOX currently uses the same indicator to
> avoid it getting a link.
>
> See the "Emphasis" section in http://dlang.org/ddoc.html

I see.

-- 
/Jacob Carlborg

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.

On Sunday, 29 December 2013 at 17:38:55 UTC, 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.

bootDoc[1] fixes this (thanks to Denis) with a number of standard macros that are reasonably easy to use[2].

It also uses JavaScript to "fix" (insofar as JS is a fix for anything) the issue of page anchors not supporting nested symbols properly.

[1] https://github.com/JakobOvrum/bootDoc

[2] https://github.com/JakobOvrum/bootDoc/wiki/Macros

On 2013-12-30 05:05, H. S. Teoh wrote:

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

Yeah, that's another problem.

-- 
/Jacob Carlborg

30-Dec-2013 14:19, Jacob Carlborg пишет:
> On 2013-12-30 05:05, H. S. Teoh wrote:
>
>> 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.)
>
> Yeah, that's another problem.

And couple of years old at that...

-- 
Dmitry Olshansky

On 2013-12-30 10:43, Jakob Ovrum wrote:

> bootDoc[1] fixes this (thanks to Denis) with a number of standard macros
> that are reasonably easy to use[2].

Based on the documentation it looks like it has the same problems as the current approach, that is:

* Multiple macros are needed for something that at most one single macro should be needed

* Doesn't work for arbitrary deep hierarchies

Also, it feels like a workaround for something that should be fixed in the compiler.

-- 
/Jacob Carlborg

On 2013-12-29 19:35, Sönke Ludwig wrote:

> This is done for the DDOX based docs that were supposed to end up on the
> home page at some point:

BTW, although DDOX seems to be the best solution currently. It still feels like a workaround for something that should be fixed in the compiler.

-- 
/Jacob Carlborg

On Monday, 30 December 2013 at 10:23:25 UTC, Jacob Carlborg wrote:
> Based on the documentation it looks like it has the same problems as the current approach, that is:

Yep, its only benefit is that it's a standardized set of macros and works for any reasonably deep hierarchy.

bootDoc is about doing the best that is possible within the limitations of DDoc. I think it is a better example of DDoc's best than Phobos, as it's much cleaner and actually has documentation.

That said, DDoc's best is hardly impressive.