Typedoc: Update docs to show examples of cross-linking

[kamranayub]

Currently docs don't show how to cross-link, it's only mentioned. Main question: does it need to be fully qualified?

[sebastian-lenz]

You can reference symbols (classes, functions, modules, etc.) using double brackets. Internally we use Reflection.findReflectionByName to resolve the link within the current context. The function tries to find a child with the given name and if no child matches will loop through all parent symbols searching their children till it hits the global space. At this point we search through all known reflections for the given name. The search is aware of hierarchical names but doesn't expect/require fully qualified names though it should work to.

Did you encounter any problems linking to other symbols?

[kamranayub]

Not yet, we haven't tried--we just weren't sure how it worked and I looked at the docs but didn't see an explanation. We just moved from YUIDoc to TypeDoc so we haven't yet changed all the old tags.

[kamranayub]

Ah I just tried and the docs said "double angle brackets" so I thought it was <<Foo>> but you said in your comment "double brackets" and that worked. Would be good to add this explanation and example(s) to the docs.

[oising]

I'm new to this, but I expected JSDodc {@link ...} to work for cross-linking to types and properties. Am I wrong?

http://usejsdoc.org/tags-inline-link.html

Update: Ah, I see - it's markdown. That said, principle of least surprise says JSDoc should work (in addition?)

[sebastian-lenz]

Hi oising, next version will support {@link ...} tags.

[blakeembrey]

@sebastian-lenz Sorry to chime in with a slightly off-topic note, but can the docs for typedoc be updated to say square brackets instead of angle brackets? Maybe write how it's resolved in the docs too. Just has a couple of surprises with that.

[sebastian-lenz]

Hi Blake, the docs are really outdated, sorry. They are on my list for a very long time. Maybe it would be better to remove them temporary and put them back online once they are up to date.

[grofit]

has this link support stuff been added? as I have just picked this lib up to use and its great but the lack of up to date docs or even a quick link saying "go to http://usejsdoc.org/ for info" would have been great.

[cancerberoSgx]

You can reference symbols (classes, functions, modules, etc.) using double brackets. Internally we use Reflection.findReflectionByName to resolve the link within the current context. The function tries to find a child with the given name and if no child matches will loop through all parent symbols searching their children till it hits the global space. At this point we search through all known reflections for the given name. The search is aware of hierarchical names but doesn't expect/require fully qualified names though it should work to.

Did you encounter any problems linking to other symbols?

I understand the logic behind going from children to parent symbols but, that implies that is not possible to reference a global symbol if there is a child with the same name. It would be great if I can reference the global namespace somehow so I can define absolute links to global symbols. Example:

export function foo(){} // global 'foo'
class A{
foo(){} //local foo
/** {@link foo} I want to reference global function 
foo but I can't - it will reference method foo(). 
Suggestion: {@link @global.foo} or perhaps {@link /foo} 
so I can reference global symbols "absolutely" */
bar(){}
}

In case I'm not missing something, would this change be acceptable for a PR? Should I create a separate issue for this ?

Otherwise, change the logic and search from parents to child, that way I can always reference global stuff and for local stuff I must use absolute paths in case of collision.

Thanks, keep it up

[aciccarello]

@cancerberoSgx Thanks for the suggestion. Microsoft is working on defining an unambiguous way to reference other symbols (Microsoft/tsdoc#9) that I think TypeDoc should eventually implement. I'd be hesitant to implement any changes to reference lookups before that is finalized. It would probably be good to open an issue to discuss this further.

[PissedCapslock]

My related question to this on SO: https://stackoverflow.com/q/58429798/1076463 .

The scenario described there does not work. A bit of debugging shows that:

• In the DeclarationReflection, the name of the module is "\"modulename.d\"" . Note the -- extra quotes around the name -- the extra.d` in the name
• Seeing this, I thought I could solve it by using {@link "modulename.d"}. However, the arg.split('.') in Projects#findReflectionByName(arg: string | string[]): Reflection | undefined converts that modulename.d into d

What does work is:

• In a module.d.ts file having a link to another module located in a .ts file (and not a .d.ts file)
• The link must then contain the extra quotes :-( . Not ideal, but it does work.

Edit: just submitted PR https://github.com/TypeStrong/typedoc/pull/1117 for this.