dlang / ddox

Advanced D documentation engine
MIT License
63 stars 21 forks source link

More lenient lookups cross-linking #132

Open Abscissa opened 8 years ago

Abscissa commented 8 years ago

When using backticks, ddox will cross-link between symbols within the same module. But to cross-link to a symbol in a different module, the fully-qualified name must be used. This can lead to excess verbosity in the documentation, so it would be really nice if non-fully-qualified symbols (if not found in the current module) are still looked up in other modules (at least if they're not ambiguously found in more than one other module).

s-ludwig commented 8 years ago

That could lead to some surprising results, if, for example, a local variable has the same name as a symbol of a foreign module*. At least without semantic analysis there would be no way to tell which of the two is meant.

But maybe instead of just searching for any symbol, a good approximation would be to follow the import statements in the documented module/container (I think the JSON output contains those). That should cover most cases and due to the anti-hijacking semantics should be safe from making the wrong guess.

* To be fair, the same rule is already used when looking up base classes/interfaces, so if this is implemented in improved form, that code should also use the improved approach.

Abscissa commented 8 years ago

That could lead to some surprising results, if, for example, a local variable has the same name as a symbol of a foreign module*. At least without semantic analysis there would be no way to tell which of the two is meant.

Yea, that's why I was thinking:

  1. Only look in other modules if it's not found in this one.
  2. If it's not in the current module, but IS in several other modules, then just dont bother linking unless there's some goos way to know which is correct.
s-ludwig commented 7 years ago

The other way around is now implemented: A fully qualified name will have its module path prefix stripped in the documentation (hovering over the link will still show the FQN).

Another safe improvement would of course be to follow import statements, which are included in the JSON output (not sure whether that has always been the case).