Cross referencing in Ddoc

[Sönke Ludwig]

Am 30.12.2013 16:57, schrieb Andrei Alexandrescu:
> On 12/30/13 3:39 AM, Sönke Ludwig wrote:
>> Am 30.12.2013 11:24, schrieb 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.
>>>
>>
>> Although I think that it is more important to have a well defined
>> documentation format that can be processed by external tools, it would
>> indeed be much nicer if for example DMD could automatically emit $(XREF
>> ...) or similar for recognized symbol names.
> 
> I'm not sure automatic cross-references are a good thing. Too many
> litter the document with links, and catch casual uses of words that
> happen to be indexable (consider e.g. "in" would be cross-referenced
> automatically).
> 
> 
> Andrei
> 
> 

In my experience it is far more annoying to have the source files
littered with $(MACROS) instead of putting a few _underscores to avoid
bogus links (not to mention that most of the time this results in no
links at all due to laziness). In some modules it may happen more
frequently, but in general this seems to be rare enough for not really
having to worry about it - at least in the examples that I've seen up to
now.

Also remember that you often have to escape such words anyway, because
they would otherwise still be highlighted as D code even without the
cross references.