plugin/outerDocs 📕🪐

[klm127]

Q	A
Bug fix?	no
New feature?	yes
Breaking change?	no
Deprecations?	no
Tests added?	yes
Fixed issues	#1770
License	Apache-2.0

This adds a new plugin to jsdoc called outerdocs.

Users of this plugin can define external namespace links in their configuration object and quickly reference them with the @outerdocs tag. A @see {@link} will be created for each @outerdocs tag and associated namespace.

It is used with the @outerdocs or the @od tag.

It must be configured by adding an "outerdocs" config to the jsdoc config object.

@outerdocs is passed a value consisting of period-delimited a name path with an optional #id suffix and an optional link text after a space. It constructs a @link based on the configuration parameters and adds it to the @see array.

outerdocs uses the first word in the period-delimited name path to find a configuration for that particular namespace. Depending on how the docs which are to be linked are structured, @outerdocs can build the url with slashes or dots, drop the first part of the name path or not, and append '.html' or not.

For example, the outerdocs config in conf.json might look like this:

"outerdocs": {
   "angular": {
      "url":"https://devdocs.io/angular/api/",
      "structure":"slashes",
      "appendhtml":false,
      "dropfirst":true      
    }
}

Outerdoc usage might look like this:

/**
* shows only cool stuff
* @outerdocs angular.elements.ngelement ngElement
*/
class coolWidget extends NgElement() {};

And the result is a @seeelement for each @outerdoc tag.

Equivalent to writing:

/** @see {@link https://devdocs.io/angular/api/elements/ngelement ngElement}**/

Which results in this

See:

• ngElement

rationale

I would personally use this in documentation I'm maintaining.

It's basic but flexible enough to do all sorts of documentation. It works great with MDN docs and you can define the namespaces as you like. I've linked to React and Phaser and Lodash and Bitcoin in testing.

It's an optional plugin that doesn't affect anything else.

Down the line, outerdocs could be evolve into a more full-fledged namespace resolution system, adding outerdoc links to @extends, @param, and other tags.

For now, I believe it adds a lot of functionality while being totally optional to use.

The idea for this is cause of Intersphinx, which I found pretty useful in some Python projects I worked on.

I think that any documentation generator needs to have some way of linking external documentation. This plugin brings at least some of that functionality to jsdoc. If a better solution is come up with, it will be easy to remove because it doesn't affect any other portions of the code base.

[klm127]

There's no new dependencies for this plugin, the package-lock.json should stay as the original.