Am 31.12.2013 05:39, schrieb Andrei Alexandrescu: > On 12/30/13 1:00 PM, Walter Bright wrote: >> 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. > > Your arguments are convincing. > > Andrei >
The argument in isolation is sound, no doubt. But alone it doesn't lead to a solution*. There are a lot of arguments regarding the current situation and if the decision is not to use the existing _negative rule, then all of those should be carefully taken into account. - Visual noise and effort when using $(XREF) style macros - $(XREF) isn't sufficient! A multitude of macros is actually needed - There is no standard set of macros, it's project specific -> The whole documentation needs to be revised when moving code between projects! - Macros need to be carefully crafted so that they don't encode knowledge about the final documentation/file structure - Macros alone can't cope with nested directory structures - The cognitive load for multiple such macros would very likely cause them to go unused in many cases My favorite solution would be to introduce a simple #identifier.chain or @identifier.chain syntax to let the compiler or documentation generator insert the proper links or macro calls. Using a sepecial $(REF identifier.chain) pseudo macro, like Jacob suggested, would work as well, but I can't see how the additional syntax/visual/typing overhead is justified for such a common feature - at least when trying to find an optimal solution, compared to the current macro based system it would of course still be a big improvement. But still, considering that there is precedence for the _negative approach (i.e. the problems of it are already there), I find using that acceptable, too, even if the concept is not as pretty/clean. * *Some* solution is needed. The different structure of the DDOX documentation for example makes the $(XREF) macros worthless, so they are currently completely disabled and automatic link generation is used instead.