How to define a function to be a callback implementation in JSDoc? - javascript

I defined a #callback that way :
/**
* #callback MyClass~Handler
* #param {string} target
* #param {Options} options - Original options
*/
I use it to define my class prototype :
/**
* #param {string} name - The name
* #param {MyClass~Handler} handler
* #private
*/
MyClass.prototype._builder = function(name, handler) { //...
But how to tell JSDoc that the following function has the same definition as my MyClass~Handler (something that would be like #isacallback in the following code)?
/**
* Default handler
* #isacallback {MyClass-Handler}
* #private
*/
MyClass.prototype._defaultHandler = function(target, options) { // ...

I haven't tested this, but since #callback just defines a type, couldn't you use the #type declaration?
In other words:
/**
* Default handler
* #type {MyClass-Handler}
* #private
*/
MyClass.prototype._defaultHandler = function(target, options) { // ...
See http://usejsdoc.org/tags-type.html for further info on #type.

Related

How to document a function's parameters if some are deconstructed while others are not (JSDoc)

How to document deconstructed parameters with JsDoc explains how to document params if there is only a single argument, which is being deconstructed.
I have this class to create custom events:
const EVENT_CONFIG_DEFAULTS = Object.freeze({
bubbles: true,
composed: true,
});
/**
* class for all FW custom events
*/
export class FWEvent extends CustomEvent {
#sourceEvent = null;
#sourceElement = null;
/**
*
* #param {string} name name of the event, see fw-events.js
* #param {EventInit} eventInit event configuration
* #param {Event} [sourceEvent] optional source event
* #param {HTMLElement} [sourceElement] optional source element to circumvent event retargeting
*/
constructor(name, eventInit, { sourceEvent, sourceElement }) {
super(name, { ...EVENT_CONFIG_DEFAULTS, ...eventInit });
this.#sourceEvent = sourceEvent || null;
this.#sourceElement = sourceElement || null;
}
get sourceEvent() {
return this.#sourceEvent;
}
get sourceElement() {
return this.#sourceElement;
}
}
So I have an optional third parameter which I cannot name due to limitations in destructuring.
How do I document this properly? The JSDoc shown obviously is incorrect.
You document them in the same way as you would for nested properties:
/**
* #param {boolean} x
* #param {boolean} y
* #param {Object} [stuff]
* #param {string} [stuff.bar]
* #param {string} [stuff.baz]
*/
function foo(x, y, {bar, baz}) {
}
Here's a screenshot of the tooltip displayed by VS Code IntelliSense when I mouse over foo:

Make JSDoc comment for function which takes another function as parameter

Imagine a function which accepts an "onUpdate" function as a parameter:
/**
* #param {function} onUpdate
* #returns {null}
*/
static async init(onUpdate) {
...
onUpdate(true);
};
onUpdate takes a boolean as an argument.
I want to add that arguments to #param {function} onUpdate.
Is there a way?
Some magnificent devs managed to do it on these addEventListener functions:
I think in screenshot you see typescript hint. But you can do something like this:
/**
* This callback is displayed as a global member.
* #callback someCallback
* #param {number} param1
* #param {number} param2
* #returns {number}
*/
/**
*
* #param {someCallback} cb
*/
function someFunction(cb) {
}
And see this hint

Documenting prototype property and method with JSDoc-3.3.0-alpha5

I have a class named FileDownloader and I've tried documenting it, but the properties and method declared using prototype aren't generated in the output file.
As stated on the title, I use jsdoc 3.3.0-alpha5.
Here's the code:
/**
* #class
* #memberOf module:utils
*/
FileDownloader = function() {};
/**
* #type {Boolean}
*/
FileDownloader.prototype.overwrite = false;
/**
* #type {String}
*/
FileDownloader.prototype.dir = config.dealImagePath;
/**
* #param {String} url
* #param {Function} done
* #param {Object} done.err
* #param {String} done.file
*/
FileDownloader.prototype.download = function(url, done) {
//...
};
Here is the generated document:
new FileDownloader()
| Source: path/to/file.js
Any idea?
The reason is memberOf in FileDownloader description.
You should set module before, all symbols in the file are assumed to be members of the module. http://usejsdoc.org/tags-module.html
Like this
/** #module utils */
/**
* #class
*/
var FileDownloader = function() {};
/**
* #type {Boolean}
*/
FileDownloader.prototype.overwrite = false;
...

Adding sub-properties to an existing property-list in jsdoc

I am trying to automate a particular module in our JS library and am stuck at a point where I want to define a set of properties (lets say an object that goes as construction parameter of a class).
/**
* This function initiates world peace!
* #constructor
* #param {object} defaults - The options to initiate peace.
* #param {number} defaults.issues - The number of issues being taken up.
* #param {string} defaults.source - The name of the location where process starts.
*/
var WorldPeace = function (defaults) {
// code here
};
It is well and good had all properties of the construction was defined at one location. Unfortunately, my code has a number of modules contributing to that construction properties. Lets say, at some other portion of the code (in a later file) causes to have a couple of more properties
* #param {Date} defaults.start - The date when the process started.
* #param {Date} defaults.stop - The date when the process should stop.
How do I go about adding to the original set of properties that I had previously defined for WorldPeace function? Doing something like a mixin or subclassing the properties would be going overboard! As such, if I can simply inject to a property list definition it would be great.
The easiest method is to use a record type:
/**
* This function initiates world peace!
* #constructor
* #param {{issues: number, source: string}} defaults - options to initiate peace.
*/
var WorldPeace = function (defaults) {
// code here
};
You could also implement an interface:
/** #interface */
var WordPeaceDefaults;
/** #type {number} */
WorldPeaceDefaults.prototype.issues;
/** #type {string} */
WorldPeaceDefaults.prototype.source;
/**
* This function initiates world peace!
* #constructor
* #param {WorldPeaceDefaults} defaults - options to initiate peace.
*/
var WorldPeace = function (defaults) {
// code here
};
/**
* #constructor
* #implements {WorldPeaceDefaults}
*/
function MyWorldPeaceDefaults() {}
/** #type {number} */
MyWorldPeaceDefaults.prototype.issues = 0;
/** #type {string} */
MyWorldPeaceDefaults.prototype.source = '';
WordPeace(new MyWorldPeaceDefaults);
Another way to do it would be to use a typedef:
/**
* #typedef {{
* issues: number,
* source: string
* }}
*/
var WorldPeaceOptions;
/**
* #constructor
* #param {WorldPeaceOptions} defaults
*/
var WorldPeace = function (defaults) {
// code here
};

Document object inside self executing function using JSDoc

So I have several object definitions that work like this:
(function () {
var parent= constructors.Parent.prototype;
/**
* Creates an instance of Child.
*
* #constructor
* #augments Parent
* #this {Child}
* #param {object} settings
*/
var Child= function(settings) {
constructors.Parent.apply(this, arguments); //calling parent constructor
//constructor code
}
Child.prototype= new constructors.Parent();
/**
* Method1
*
* #this {Child}
* #param {string} param1
* #param {number} param2
*/
Child.prototype.method1= function(param1, param2) {
parent.method1.apply(this,arguments); //calls "super"
//method code
}
constructors.Child= Child;
}());
I do all this so that only global variable is 'constructors' and so that I don't have to say 'construtors.Child' all the time. But JSDoc3 is ignoring my comments and generates nothing on this code. Anyone knows any special tags to fix this? I don't mind if the JSDoc shows my class name as 'Child' or 'constructors.Child', either way is fine.
use #public in front of #class/#module/#namespace
see https://github.com/jsdoc3/jsdoc/issues/442
I'm not sure if this is the right way to do it, but it worked:
On another file I now have the following:
/**
* #module constructors
*/
constructors= {}
And in the file mentioned before I now have:
/**
* #exports constructors
*/
(function () {
var parent= constructors.Parent.prototype;
/**
* Creates an instance of Child.
*
* #constructor
* #augments Parent
* #this {Child}
* #param {object} settings
*/
var Child= function(settings) {
constructors.Parent.apply(this, arguments); //calling parent constructor
//constructor code
}
Child.prototype= new constructors.Parent();
/**
* Method1
*
* #this {Child}
* #param {string} param1
* #param {number} param2
*/
Child.prototype.method1= function(param1, param2) {
parent.method1.apply(this,arguments); //calls "super"
//method code
}
constructors.Child= Child;
}());

Categories