| path | title |
|---|---|
/learnings/javascript_jsdoc |
Learnings: Javascript: JSDoc |
- Q: How can I link to a typedef in another file >
- >
- Good articles on this
- Components involved
- See also
a.js
/**
* @module MyModule
*/
/**
* @typedef MyTypdef
* @property {string} name
*/
b.js
/**
* @method foobar
* @param { module:MyModule~MyTypedef } opt options or initial config values
*/
function foobar(opt)
~ means "instance" . means static object
Typedefs (and other functions?) that aren't explicitly part of a module are put in the global namespace.
Thus if you access these from other files you don't need special syntax for your rendered jsdocs to link to them.
If you have properly put everything in a @module you can force a particular declaration to be put in the global namespace anyway. This would allow you to sacrifice a bit of namespace purity for ease of use (because you can just use the name, as if it was part of a global module).
Example
/**
* @global
* @typedef MyTypdef
* @property {string} name
*/
See ESLint_Forcing_Import_Of_Some_Identifier
We can use JSDocs + some typescript magic to achieve this.
You may - and in fact I really want - to not break jsdoc generation when doing this. There are several problems with this currently (May 2019).
Also broken: IntelliSense thinks the module: literal is a filename
Nope.
Using Clever Typescript ways to create a type then import the typedef: They don't work (with pure jsdoc)
This:
- Breaks running jsdoc, because it doesn't know what to do with the Typescript syntax in the middle of the declaration
- Looks kind of weird: you have to essentially stub every declaration from another file that you want to use.
See a good explanation of the "import type" trick and where it breaks down:
- microsoft/TypeScript#14233 (comment) <-- good example of the "typedef import" usage trick... and the error you get from jsdoc when you do it
- microsoft/TypeScript#14377 (comment) <-- breaks regular people trying to run jsdoc from command line. (Solutions proposed break normal jsdoc runs).
jsdoc-plugin-typescript lets us put typescript in our JSDoc, so we can do the Clever Typescript thing.
/**
* @typedef { import('./a').Team} Team
*/
/**
* Display the team
*
* @param {Team} team the team to display for
*/
function displayTeam(team) { ... }
It has only two (relatively minor problems):
- when it expands the typescript the type, in the rendered JS, is not hyperlinked anymore (but the type appears inline in the module page, not requiring people to go find it, so that's a win).
- Requires(?) jsdoc 3.6
- requires typedef stubs. (Placing the typescript inline in the
@paramdeclaration doesn't seem to work)
But it has some major ADVANTAGES:
- eslint, even with eslint-plugin-jsdoc seems to be relatively happy with the typescript in the stub declaration
- Typechecking / IntelliSense totally works!
See it is in use / I made a sample repo
You're likely running eslint in your project, so you have to make sure that any code you write stays valid. Because you're not really writing Typescript, you can't go down that route entirely
You are running eslint-plugin-jsdoc, right?
https://stackoverflow.com/a/50255744/224334
Can use the command prompt in VCS to select Typescript version: make sure this is > 2.9???
... which my work if both the source and caller location are in the same jsDoc module...
- microsoft/TypeScript#28162 for a potential implementation of this??
Because if TS had native support you would be able to do TS-like typechecking, even / especially if you could set your declarations (or whatever) to global.
- Typescript_Typechecking_With_JsDoc_Annotations
- https://stackoverflow.com/a/55767692/224334 <-- set up Visual Studio Code to include all the files.. but doesn't seem to work for typedefs?????