Page MenuHomePhabricator

Allow Diviner to fall back to (or link directly to) the Symbol index
Open, Needs TriagePublic


I think that @{function:array_key_exists} should link to, or example.

Event Timeline

joshuaspence raised the priority of this task from to Needs Triage.
joshuaspence updated the task description. (Show Details)
joshuaspence added projects: Diviner, Symbols.
joshuaspence added a subscriber: joshuaspence.
eadler added a project: Restricted Project.Aug 5 2016, 5:24 PM
epriestley renamed this task from Allow linking to external documentation to Allow Diviner to fall back to (or link directly to) the Symbol index.Jan 26 2018, 3:07 PM

I think a reasonable path forward here is for Diviner to have a {symbol} sort of syntax which executes a symbol index query. The symbol index can already be configured to know how to offer links to external documentation.

That leaves an open question: should the {symbol} syntax just be the same as the existing @{...} syntax?

I'm inclined to say no. Offhand: I expect linking to external documentation to be pretty rare (most comments in most software projects do not need to explain how the language's standard library works or reference library functions); and if we make them the same syntax we can't really detect typos/errors/bad links (because external symbol sources are defined dynamically at runtime). I could go either way on this, but that leaves me inclined to think we should use a separate syntax.

Another possible consideration is that after T13047 the symbol query stack potentially can handle more context information than atom queries can (path, line, character). I'm not sure any of this is ever useful in documentation, but if there is some use case for it that would suggest that {symbol} and {atom} should have different syntax, too, since the extra parameters would only make sense when referencing {symbol}.