cross linking to 3rd party libs?

[sccolbert]

I have a library which uses types from another one of my libraries (as parameters to a function). Is there a way to cross-link to the other project so that the user can click on the arg-type and be taken to that libraries documentation?

[sebastian-lenz]

Hi Chris, no, currently there is no solution to do this. All links within the documentation are resolved from the symbol ids exposed by the TypeScript compiler, external documentations cannot be resolved that way. Also external documentations might not follow the same documentation structure so there would be some kind of mapping required.

However I've discussed with the team of DefinitelyTyped about generating documentations of their definitions, there we would need a similar mechanism. I'll keep this in mind and check back on it.

[sccolbert]

Cheers! Thanks for entertaining the idea!

[PanayotCankov]

We the NativeScript framework are evaluating the typedoc tool to generate out API ref. Currently we use in-house tool but we simply do not have the manpower to keep it a top quality one. You can check the current state of our API reference here.

The issue @events issue #136 along with the option to link to other frameworks are quite important for us. The "nativescript-background-http" plugin for example uses classes from the NativeScript core, linking to the core API by somewhat fully-qualified-name would have been nice. The "EventData" base interface here could have been a link to EventData. Ofc. in case that both sites are generated with the typedoc tool.

As an idea, if the .d.ts-es are used with the typedoc tool they can be maintained by the .d.ts authors so they start with an /// <api-ref src="http://mysite.com/api-ref/v1.3.0/" /> and the triple slash comment can be used to resolve links to 3rd party documentation. The typedoc already supports a nice filter.

[sebastian-lenz]

Different documentations might use different settings, themes or versions, knowing the base url of another documentation is therefore not sufficient. I think we must generate a manifest file containing a mapping of the generated urls to the containing language elements.

This manifest file could be linked within a definition like described above (although I would prefer the linking syntax to align with the TSD header as this is the defacto standard for adding metadata to definition files). When processing the source files we would have to load that manifest and match the symbol names against it. So if you've included a definition file of a vendor supporting the manifest file format all external symbols should be linked to the original documentation accordingly.

Overall this is a quite complex process as we have to both add it to the converter component als well as to the renderer component. But as mentioned above I'm interested in this feature too and I hope it will make its way into v0.4.

[cancerberoSgx]

What I'm successfully doing, in my typedoc.js file is including the third party definitions. The only problem is you have to be carefull to not contaminate too much because typedoc will show ALL the types there. In my case is acceptable, but you probably dont want to include things like node_modules/@types/node/index.d.ts . My typedoc.js example:

module.exports = {
    src: [
        './lib/src/',
        './node_modules/ansi-escape-sequences/types/ansi-escape-sequences.d.ts',
        "./node_modules/node-pty/typings/node-pty.d.ts"
    ],
    "mode": "file",
    "includeDeclarations": true,
    "tsconfig": "tsconfig.json",
    "out": "../../docs",
    "excludePrivate": true,
    "excludeProtected": true,
    "excludeExternals": true,
    "readme": "../../README.md",
    "name": "cli-driver"
}

[StefanOrzu]

I had a nice discussion with @samuraijack and we thought of a simple mechanism for annotating imports, like this:

/**
 * @external_symbol SomeSymbol DocAlias1
 * @external_symbol SomeSymbol2 DocAlias2
*/
import { SomeSymbol1, SomeSymbol2 } from "some-third-party-library";
/**
* @external_symbol Component angular:Component
*/
import { Component} from "@angular/core";

where DocAlias1 and DocAlias2 are internally recognised aliases which can be mapped in the typedoc configuration to external URLs provided by their vendors.

The advantage of using aliases is that

• they allow the user to avoid hardcoding URLs accros their codebase, therefore eliminating a lot of duplication.
• when upgrading a 3rd party library to a newer version, the user would only need to update the URLs in the configuration instead of manually updating tens or hundreds of source files.
• there could be a system in place to flag external symbols that are in the process of deprecation

The API doc generator could render these external symbols a links to their mapped URLs (opening in a new tab).

I see potential for adding different plugins for closer integration with different other formats of API docs for a more seamless experience.

An example configuration could be:

{
  ...
  "externalSymbolAliasMapping": {
    "angular:Component": {
       "type": "angular-docs", // or whatever their docs framework is called
       "docURL": "https://angular.io/api/core/Component",
       "deprecated": false // should be default
     }
  }
}

[canonic-epicure]

@Gerrit0 Great addition, thank you!