If I have a function signature defined either in JSDoc with #callback or in a .t.ds library using type, can I somehow use JSDoc to "attach" that signature to multiple function definitions?
/**
* #callback ruleDefiner
* #param {RuleDefinitionBuilder} builder
*/
Then:
/** #thisFunctionIsA {ruleDefiner} */
function spellfix(builder) {
// The IDE should know that builder is a RuleDefinitionBuilder
const {depends, produces, cmd, T} = builder;
const input = depends("foo.txt");
const output = produces("foo.spellfixed.txt");
cmd(T`spellfix ${input} > ${output}`);
}
/** #thisFunctionIsA {ruleDefiner} */
function sign(builder) {
// The IDE should know that builder is a RuleDefinitionBuilder
const {depends, produces, cmd, T} = builder;
const input = depends("foo.spellfixed.txt");
const output = produces("foo.signed.txt");
cmd(T`sign ${input} > ${output}`);
}
What should I use instead of pseudo-JSDoc #thisFunctionIsA?
Yes, you can, using the #type tag.
/**
* #callback ruleDefiner
* #param {RuleDefinitionBuilder} builder
*/
/** #type {ruleDefiner} */
function spellfix(builder) {
// The IDE should know that builder is a RuleDefinitionBuilder
const {depends, produces, cmd, T} = builder;
const input = depends("foo.txt");
const output = produces("foo.spellfixed.txt");
cmd(T`spellfix ${input} > ${output}`);
}
/** #type {ruleDefiner} */
function sign(builder) {
// The IDE should know that builder is a RuleDefinitionBuilder
const {depends, produces, cmd, T} = builder;
const input = depends("foo.spellfixed.txt");
const output = produces("foo.signed.txt");
cmd(T`sign ${input} > ${output}`);
}
EDIT:
If this is truly/strictly for JSDoc, see this JSDoc documentation for more. However, if you, like me, only use JSDoc with JavaScript for IntelliSense in your editor, you probably want this TypeScript documentation (which JavaScript IntelliSense is actually using) instead.
Related
I'm trying to get jsdoc (version 3.6.7, using node 16) to turn my documented js code into actual documentation, but no matter what I do it just generates an out directory with an index.html that is primarily empty lines, rather than documentation. I've asked about this over on the issue tracker (after I searched the docs and the web for information on what one might be doing wrong to get jsdoc to generate empty files, but I can't for the life of me find anything useful that addresses that) but since it's been a few days, it feels useful to ask here as well, so that an answer in either place can be cross posted.
Running the jsdoc command does not flag any errors with the input, and completes with a normal zero exit code but generates nothing useful, so hopefully someone here's run into his before and can explain what is necessary in addition to the follow code to actually get jsdoc to generate docs.
An example of code that has no errors according to jsdoc, but also yields no docs whatsoever:
import { Errors } from "../errors.js";
import { Models } from "./models.js";
/**
* Several paragraphs of text that explain this class
*
* #class
* #namespace model
*/
export class Model {
/**
* #ignore
*/
static ALLOW_INCOMPLETE = Symbol();
/**
* Also several paragraphs explaining the use of this function.
*
* #static
* #param {*} data
* #param {*} allowIncomplete (must be Model.ALLOW_INCOMPLETE to do anything)
* #returns {*} a model instance
* #throws {*} one of several errors
*/
static create = function (data = undefined, allowIncomplete) {
return Models.create(
this,
data,
allowIncomplete === Model.ALLOW_INCOMPLETE
);
};
/**
* code comment that explains that if you're reading
* this source, you should not be using the constructor,
* but should use the .create factory function instead.
*
* #ignore
*/
constructor(caller, when) {
if (!caller || typeof when !== "number") {
const { name } = this.__proto__.constructor;
throw Errors.DO_NOT_USE_MODEL_CONSTRUCTOR(name);
}
}
}
Running this with jsdoc test.js yields an out dir with an index.html and test.js.html file, the first containing some thirty newlines of "no docs here" with boilerplate wrapper HTML code, and the second containing the original source code with nothing else useful either.
What else does one need to do to get jsdoc to actually generate documentation here?
I have fixed it by not using export infront of classes, instead exporting them at the end of the file. like this:
import { Errors } from "../errors.js";
import { Models } from "./models.js";
/**
* Several paragraphs of text that explain this class
*
* #class
* #namespace model
*/
class Model {
/**
* #ignore
*/
static ALLOW_INCOMPLETE = Symbol();
/**
* Also several paragraphs explaining the use of this function.
*
* #static
* #param {*} data
* #param {*} allowIncomplete (must be Model.ALLOW_INCOMPLETE to do anything)
* #returns {*} a model instance
* #throws {*} one of several errors
*/
static create = function (data = undefined, allowIncomplete) {
return Models.create(
this,
data,
allowIncomplete === Model.ALLOW_INCOMPLETE
);
};
/**
* code comment that explains that if you're reading
* this source, you should not be using the constructor,
* but should use the .create factory function instead.
*
* #ignore
*/
constructor(caller, when) {
if (!caller || typeof when !== "number") {
const { name } = this.__proto__.constructor;
throw Errors.DO_NOT_USE_MODEL_CONSTRUCTOR(name);
}
}
}
export {Model}
Turns out this was posted too early: taking the time to start at the official documentation for classes over on https://jsdoc.app/tags-class.html and running that example through jsdoc works perfectly fine, and subsequently building out that example to match the actual file's code yields working documentation just fine, too.
And in this specific case, there were several problems:
adding #namespace paired with #class was the main problem. Neither were necessary, but the #namespace entry changes how jsdoc parses the rest of a file's documentation, where if methods are to show up, they must use a #name property that includes that namespace. As that was not the case here, nothing ended up showing in the documentation.
having an #ignore on the constructor function, rather than using the #hideconstructor property on the class meant that even with #namespace removed, no documentation got written. JSdoc treats the class docs heading and the constructor as the same thing, so #ignoreing the constructor is treated the same as ignoring the entire class.
Fixing both mistakes, and removing the unnecessary #class at the top, gives perfectly fine documentation:
import { Errors } from "../errors.js";
import { Models } from "./models.js";
/**
* Several paragraphs of text that explain this class
*
* #hideconstructor
*/
export class Model {
/**
* #ignore
*/
static ALLOW_INCOMPLETE = Symbol();
/**
* Also several paragraphs explaining the use of this function.
*
* #static
* #param {*} data
* #param {*} allowIncomplete (must be Model.ALLOW_INCOMPLETE to do anything)
* #returns {*} a model instance
* #throws {*} one of several errors
*/
static create = function (data = undefined, allowIncomplete) {
return Models.create(
this,
data,
allowIncomplete === Model.ALLOW_INCOMPLETE
);
};
/**
* code comment that explains that if you're reading
* this source, you should not be using the constructor,
* but should use the .create factory function instead.
*/
constructor(caller, when) {
if (!caller || typeof when !== "number") {
const { name } = this.__proto__.constructor;
throw Errors.DO_NOT_USE_MODEL_CONSTRUCTOR(name);
}
}
}
I want to document a function expression from some example Alexa SDK code.
This person seems to know what they're doing, except the jsdoc linter doesn't like the inline import like this:
#param {import('ask-sdk-core').HandlerInput} handlerInput
so I just used the standard require at top of file workaround.
const { HandlerInput } = require('ask-sdk-core')
and then inline:
#param {HandlerInput} handlerInput - blah
Intellisense loves it, everything seems great...
except JSDOC gives me nothing:
I seem to have all other aspects of jsdoc working perfectly and everything documents beautifully.
Except this.
I have tried referencing the constant as almost every type, scoured github, read things link the following:
JSDoc not recognizing exported function
JSDOC: How to document inner variables of function
Here's a slimmed down abridged version of the example code I linked to above. What have I missed or got wrong? Any ideas appreciated. Thanks.
const { HandlerInput } = require('ask-sdk-core')
/** #constant */
const audioController = {
/**
* Handles the creation of a response with an AudioPlayerPlayDirective, relying on previously set playbackInfo values. Also updates certain appSettings to maintain correct state of the skill.
*
* #param {HandlerInput} handlerInput - defined by Alexa
* #returns {Promise<HandlerInput.Response>} alexa response object
*/
async play (handlerInput) {
const speakOutput = 'playing'
return handlerInput.responseBuilder.speak(speakOutput).getResponse()
},
/**
* Handles the creation of a response with an AudioPlayerStopDirective
*
* #param {HandlerInput} handlerInput - defined by Alexa
* #returns {object} alexa response object
*/
stop (handlerInput) {
const speakOutput = 'stopping'
return handlerInput.responseBuilder.speak(speakOutput).getResponse()
}
}
module.exports = { audioController }
Thanks to #customcommander for the guidance, I was then able to find this Q&A which pointed me towards the following solution. Unfortunately, VSCode intellisense doesn't "see" namespace definitions in separate files, although jsdoc has no problem.
It seems like jsdoc doesn't require #memberof, but from what I can find it's good practice(?) and does no harm. Many thanks for the help.
/**
* Audiocontroller namespace
*
* #namespace audioController
*/
const audioController = {
/**
* Handles the creation of a response with an AudioPlayerPlayDirective
*
* #param {HandlerInput} handlerInput - defined by Alexa
* #memberof audioController
* #returns {object} alexa response object
*/
async play (handlerInput) {
const speakOutput = 'playing'
return handlerInput.responseBuilder.speak(speakOutput).getResponse()
},
/**
* Handles the creation of a response with an AudioPlayerStopDirective
*
* #param {HandlerInput} handlerInput - defined by Alexa
* #memberof audioController
* #returns {object} alexa response object
*/
stop (handlerInput) {
const speakOutput = 'stopping'
return handlerInput.responseBuilder.speak(speakOutput).getResponse()
}
}
module.exports = { audioController }
I need to add a function attached to a node in this way:
myElement = querySelector('#myElement');
myElement.moveMe = () =>{
//move Me Code;
}
But I do not know how to document this function (and also prevent lint errors), I tried use #extends with a #typedef but it says that it just works with constructors.
I might suggest that the right way to do this would be to create an object with {el: myElement, moveMe: ()=>{}} myself, but if you must extend, it looks like this:
/**
* #constructor
* #extends {HTMLElement}
*/
const NewType = function() {};
/** #type {function()} */
NewType.prototype.moveMe = function(){};
/** #type {NewType} */
const myElement = /** #type {NewType} */ (document.querySelector('body div'));
myElement.moveMe = () =>{
//move Me Code;
console.log('dont remove me');
}
Error free
(Not sure about your stack, just noting my 2C from recent (2019-Q1) personal VSCode JSDoc struggles.)
In theory, it seems it should be possible to use simple #typedef with "parent" type declaration: (this does not work)
/**
* #typedef {HTMLElement} movableElement
* #property {function} moveMe
*/
/** #type movableElement */
var myElement = document.querySelector('#myElement');
myElement.moveMe; // NOPE, not present for some reason :(
myElement.tabIndex; // ok, this is from HTMLElement
Closest to intention of extending native HTML elements with custom properties was to & "Intersection Type notation" I learned about from this comment either using helper type:
/**
* #typedef movable
* #property {function} moveMe
*/
/**
* #typedef {HTMLElement & movable} movableElement
*/
/** #type movableElement */
var myElement = document.querySelector('#myElement');
myElement.moveMe; // ok
myElement.tabIndex; // ok (HTMLElement properties are present as well)
Or even without helper type, with direct intersection:
/**
* #typedef {HTMLElement & {moveMe: function}} movableElement
*/
/* ... */
Strangely, any #property declaration added to such extended type seems to be completely ignored (just like our property in the first failed attempt, I'm still not sure why).
I've been struggling to achieve something similar - extend HTMLElement with some hacky custom properties in JavaScript in VSCode - and after exhaustive SO / github / docs diving this workaround-ish solution quite worked for me.
Assuming I have a typedef type in a js module
// somewhere/foo.js
/**
* #module
*/
/**
* #typedef Foo
* #type {object}
* property {string} bar - some property
*/
Is it possible to reference this type in another module, so that in the HTML page generated by jsdoc, the type is displayed as a link to the typedef-ed module ?
I tried variations of this, but nothing seems to work...
// somewhere_else/bar.js
/**
* #module
*/
/**
* #param {somewhere/foo/Foo} foo - some param
*/
export default function doStuff(foo) {
...
}
This works for me ...
// somewhere/foo.js
/**
* #module foo
*/
/**
* #typedef module:foo.Foo
* #type {object}
* #property {string} bar - some property
*/
and ...
// somewhere_else/bar.js
/// <reference path="foo.js" />
/**
* #module bar
*/
/**
* #param {module:foo.Foo} foo - some param
*/
function doStuff(foo) {
//...
};
The above answer shows up high in search results so I'm documenting what worked for me in case it helps someone in a similar situation.
I'm using Visual Studio code for a node project with // #ts-check on all my modules. Using the above syntax hiccups on the module: syntax. Also, the code assistance doesn't work properly. It took me a while but the answer ended up being quite simple
If I have the typedef myTypedef in a module myModule then in the second module where I require myModule
mm = require(myModule)
I can use something like
/** #param {mm.myTypedef} myParamName */
The module syntax is not supported by TypeScript so if you're getting here assuming it to work, I haven't been able to get the solutions above to work.
To get it working with TypeScript use Import Types
For the OP the way I would do it is
// foo.d.ts
export type Foo = {
/**
* some property
*/
bar: string,
};
Then refer to it in the JS module as
/**
* #typedef { import("./foo").Foo } Foo
*/
/**
* #param {Foo} foo - some param
*/
export default function doStuff(foo) {
...
}
You can verify things are working on an individual file more strictly by adding the following to the beginning of the file. This will enable typescript checking in Visual Studio code for the specific file to help prepare your move to Typescript in the future.
// #ts-check
Many libraries export types from their root file, to access those in typedefs, change your import to use the import * as format.
For example:
import * as testingLibrary from '#testing-library/react';
/**
* #returns {testingLibrary.RenderResult}
*/
export function myCustomRender() { }
I've tried both of the above approaches.
Firstly, in the case of #typedef module:foo.Foo, VSCode treated the usage of Foo within the same file as any. Which I didn't find acceptable.
Secondly, when using ES6 imports the following issue emerges:
import foo from 'foo'
/** #param {foo.Foo} a - Error Foo does not exist on foo */
On the other hand VSCode recognizes import { Foo } from 'foo' without even using the JSDoc module syntax:
/**
* #module bar
*/
What's more I was also able to reference a property on the imported type, namely:
import { Foo } from 'foo'
/** #param {Foo['bar']} bar */
Note
This project uses Babel and assume compiling code which uses type imports in not feasible without a transpiler.
I'm working with vscode-powertools script which provides access to vscode module at runtime (as opposed to it being available to VSCode at edit time via the local node_modules).
If I would try to import the types with the usual jsdoc import
//#ts-check
/** #typedef {import('c:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode').TextEditor} TextEditor */
I would be getting the File is not a module error:
File 'C:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode/vscode.d.ts' is not a module. ts(2306)
So here's the trick I'm using to typecheck that kind of script:
//#ts-check
/// <reference types="c:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode" />
// Allows us to reference the `vscode` module with jsdoc `#type`
async function vscodeⁱ() {if (1 == 1) return null; return import ('vscode')}
exports.execute = async (args) => {
// Allows us to reference the `vscode` module with jsdoc `#type`
const vscode = await vscodeⁱ()
/** #type {vscode} */
const vs = args.require ('vscode')
// NB: The following code is fully typed in VSCode
const windowᵛ = vs.window
const editorᵛ = windowᵛ.activeTextEditor
const start = editorᵛ.selection.start
}
I'm brand new to JSDoc, and I'm trying to figure out the best way to tag my code. For some reason after I label something as a #class, I can't get anything to appear as #inner:
/**
* The logger, to simply output logs to the console (or potentially a variable)
* #class Logger
* #requires 'config/globalConfig'
*/
define(["config/globalConfig"], function (config) {
/**
* Instantiate a new copy of the logger for a class/object
* #constructor
* #param name {string} - The name of the class instantiating the logger
*/
return function (name) {
/**
* #memberOf Logger
* #type {string}
*/
this.name = name;
/**
* Place the message on the console, only for "DEV" level debugging
* #function
* #memberOf Logger
* #param message {string}
*/
this.debug = function (message) {
... some code ...
};
};
});
Right now all the members are appearing as <static>. If I add the #inner tag to any of the attributes/functions they vanish completely from the output.
Edit: I also forgot to mention. The #constructor flag doesn't seem to be working either. If I remove that entire section, it appears the same in the output. The output does not include the #param that I would like to mention with my constructor.
Please let me know if this is completely off, I'm just kind of guessing here since the JSDoc3 documentation is a bit difficult to read.
So I figured it out, still not sure if it's absolutely correct. I had to use "Logger~name" to have it appear correctly as an inner function. According to the JSDoc documentation, this ~ is "rarely used". Seems to be the only thing that works for me.
define(["config/globalConfig"], function (config) {
/**
* The logger, to simply output logs to the console (or potentially a variable)
* #class Logger
* #param name {string} - The name of the class instantiating the logger
*/
return function (name) {
this.name = name;
/**
* Place the message on the console, only for "DEV" level debugging
* #function Logger~debug
* #param message {string}
*/
this.debug = function (message) {
... code ...
};
};
});