On 12/29/2013 9:38 AM, Jacob Carlborg wrote:
> 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.

This will create many unwanted links, in three scenarios:

1. In the description for S, there should not be hyperlinks to S. These would be annoying - when you click on them, nothing will happen.

2. Using the word S as a word, not in reference to symbol S, would generate a hyperlink which would not make sense.

3. If there are multiple symbols S, hyperlinks to the wrong one would be created. This is worse than useless.

In my adding of such hyperlinks, 1..3 happen regularly, this is not a "may" happen. It's a "will" happen, a lot.

On 2013-12-30 20:08, Walter Bright wrote:

> This will create many unwanted links, in three scenarios:

I don't think so, see below.

> 1. In the description for S, there should not be hyperlinks to S. These
> would be annoying - when you click on them, nothing will happen.

The compiler knows which symbol it currently generating documentation for, just exclude that.

> 2. Using the word S as a word, not in reference to symbol S, would
> generate a hyperlink which would not make sense.

I've have seen that happened a couple of times with documentation generators that support it, it has never bother me. As Sönke has said, you can solve that by appending an underscore and the compiler would not create a link of the symbol.

> 3. If there are multiple symbols S, hyperlinks to the wrong one would be
> created. This is worse than useless.

Most of the times there are not multiple symbols with the same name, the language make sure of that. Although there will be a problem with function overloading.

> In my adding of such hyperlinks, 1..3 happen regularly, this is not a
> "may" happen. It's a "will" happen, a lot.

I don't agree, I don't think it's a problem. It's far better than having to add macros everywhere instead.

-- 
/Jacob Carlborg

Am 30.12.2013 20:08, schrieb Walter Bright:
> On 12/29/2013 9:38 AM, Jacob Carlborg wrote:
>> 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.
> 
> This will create many unwanted links, in three scenarios:
> 
> 1. In the description for S, there should not be hyperlinks to S. These would be annoying - when you click on them, nothing will happen.

This one can easily be implemented by the documentation generator.

> 
> 2. Using the word S as a word, not in reference to symbol S, would generate a hyperlink which would not make sense.

The _S scheme can be used to avoid the hyperlink.

> 
> 3. If there are multiple symbols S, hyperlinks to the wrong one would be created. This is worse than useless.

If the same lookup rules are used as for the D code itself, the results should turn out pretty much as expected. DDOX currently doesn't follow imports correctly, yet, but even with just a simple hierarchical lookup in the current scope and a fallback to a global lookup (across all symbols) this seems to work pretty well.

> 
> In my adding of such hyperlinks, 1..3 happen regularly, this is not a "may" happen. It's a "will" happen, a lot.
> 

It will happen, but you have to weigh disabling these places manually against having to add an explicit link every time. From what I've seen so far, the latter means a *lot* more work.

Personally, I'd prefer an explicit, but unobtrusive, marker like Doxygen uses (e.g. "func()", "::func" or "#func" are recognized as cross references). But since the _ rule is already there, it seems to be a natural choice.

Am I slow... ;)

On 12/30/2013 12:14 PM, Jacob Carlborg wrote:
> On 2013-12-30 20:08, Walter Bright wrote:
>
>> This will create many unwanted links, in three scenarios:
>
> I don't think so, see below.
>
>> 1. In the description for S, there should not be hyperlinks to S. These
>> would be annoying - when you click on them, nothing will happen.
>
> The compiler knows which symbol it currently generating documentation for, just
> exclude that.

That's true.


>> 2. Using the word S as a word, not in reference to symbol S, would
>> generate a hyperlink which would not make sense.
>
> I've have seen that happened a couple of times with documentation generators
> that support it, it has never bother me. As Sönke has said, you can solve that
> by appending an underscore and the compiler would not create a link of the symbol.

While possible, I'm not too enamored with this. It makes for a maintenance problem. Add a new symbol to a module, and then you have to manually search for any other instances of the word. Naturally, the latter won't get done, and you're left with nonsense links in the doc.


>> 3. If there are multiple symbols S, hyperlinks to the wrong one would be
>> created. This is worse than useless.
>
> Most of the times there are not multiple symbols with the same name, the
> language make sure of that. Although there will be a problem with function
> overloading.

I've run into this a few times, and it cannot be dismissed easily. Worse, there is the issue of how one overrides the auto-link generation to be the right link.


> It's far better than having to add
> macros everywhere instead.

I'll have to disagree on that. I just finished doing it with std.datetime, and it didn't take more than a few minutes with global query-search-replace.

On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
> Oh the default is to link and then disable manually? That's still manual, just
> the default is different :o). I can work with that.

As I mentioned elsewhere, I dislike the requirement to use the inverse feature. Consider maintenance - I add a symbol, and then have to grep the rest of the module for any inadvertent collisions? Features should be positive ones, not negative.

Am 30.12.2013 21:58, schrieb Walter Bright:
>>> 2. Using the word S as a word, not in reference to symbol S, would generate a hyperlink which would not make sense.
>>
>> I've have seen that happened a couple of times with documentation
>> generators
>> that support it, it has never bother me. As Sönke has said, you can
>> solve that
>> by appending an underscore and the compiler would not create a link of
>> the symbol.
> 
> While possible, I'm not too enamored with this. It makes for a maintenance problem. Add a new symbol to a module, and then you have to manually search for any other instances of the word. Naturally, the latter won't get done, and you're left with nonsense links in the doc.
> 

True, but I'd argue that this is really the exception. New symbols also influence just the documentation of the current scope (i.e. a new class member won't affect the documentation of other classes in the same module).

> 
>>> 3. If there are multiple symbols S, hyperlinks to the wrong one would be created. This is worse than useless.
>>
>> Most of the times there are not multiple symbols with the same name, the
>> language make sure of that. Although there will be a problem with
>> function
>> overloading.
> 
> I've run into this a few times, and it cannot be dismissed easily. Worse, there is the issue of how one overrides the auto-link generation to be the right link.

Qualified names. The qualifying prefix could be hidden from the user or displayed as is. But after all it also provides useful information to the reader, as it's now possible to tell which symbol is meant without following the link first.

On 12/30/2013 12:33 PM, Sönke Ludwig wrote:
> [...]

I've pretty much replied to these points in my response to Jacob and Andrei.

Am 30.12.2013 22:00, schrieb Walter Bright:
> On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
>> Oh the default is to link and then disable manually? That's still
>> manual, just
>> the default is different :o). I can work with that.
> 
> As I mentioned elsewhere, I dislike the requirement to use the inverse feature. Consider maintenance - I add a symbol, and then have to grep the rest of the module for any inadvertent collisions? Features should be positive ones, not negative.
> 

I agree the reverse would be better, but that's what is already in DDOC now. Also, quoting http://dlang.org/ddoc.html:

> Identifiers in documentation comments that are function parameters or
are names that are in scope at the associated declaration are emphasized in the output.

So the same problem is already reality - you already have to go through the documentation to see if there are any mis-highlighted words.

On 2013-12-30 21:58, Walter Bright wrote:

> I've run into this a few times, and it cannot be dismissed easily.
> Worse, there is the issue of how one overrides the auto-link generation
> to be the right link.

I guess that would require a macro.

> I'll have to disagree on that. I just finished doing it with
> std.datetime, and it didn't take more than a few minutes with global
> query-search-replace.

How did you limit that search to only the documentation?

-- 
/Jacob Carlborg