I've copied an example from here. Below is the example code, but the problem is that Store.TAX_RATE shows up in the documentation as a property of Item and not as a property of the module Store. Any suggestions why ?
Example code:
/**
* This module contains classes for running a store.
* #module Store
*/
var Store = Store || {};
/**
* `TAX_RATE` is stored as a percentage. Value is 13.
* #property TAX_RATE
* #static
* #final
* #type Number
*/
Store.TAX_RATE = 13;
/**
* #class Item
* #constructor
* #param name {String} Item name
* #param price {Number} Item price
* #param quantity {Number} Item quantity (the number available to buy)
*/
Store.Item = function (name, price, quantity) {
/**
* #property name
* #type String
*/
this.name = name;
/**
* #property price
* #type String
*/
this.price = price * 100;
/**
* #property quantity
* #type Number
*/
this.quantity = quantity;
/**
* #property id
* #type Number
*/
this.id = Store.Item._id++;
Store.Item.list[this.id] = this;
};
That's because according to YUIDoc terminology a module is just a collection of related classes, so it can't contain anything but classes.
What you could do instead is to document Store and Store.Item both as classes:
/**
* This module contains classes for running a store.
* #class Store
*/
var Store = Store || {};
/**
* `TAX_RATE` is stored as a percentage. Value is 13.
* #property TAX_RATE
* #type Number
*/
Store.TAX_RATE = 13;
/**
* #class Store.Item
*/
Store.Item = function (name, price, quantity) {
};
Related
I'm trying to type the eslint-local-rules.js file using jsdoc, but I can't figure out how to make #template with the default value for the RuleFunction. My goal is to remove the import('#typescript-eslint/utils/dist/ts-eslint') from the #type of the ArrowFunctionExpression class, but if I use the current typedef RuleFunction, its value will be
but I want to get as from the library
/**
* #typedef {import('#typescript-eslint/utils/dist/ts-estree').TSESTree} TSESTree
* FIXME: how to make the default template TSESTree.BaseNode?
* // # template {TSESTree.BaseNode=} T
* #typedef {import('#typescript-eslint/utils/dist/ts-eslint').RuleContext} RuleContext
* #typedef {import('#typescript-eslint/utils/dist/ts-eslint').RuleFunction} RuleFunction<T>
*/
module.exports = {
'end-api-functions-with-api': {
/**
* #param {Readonly<RuleContext<string, unknown[]>>} context
* #returns
*/
create(context) {
/**
* absolute file path
* #type {string}
*/
const filename = context.getFilename()
/**
* current working directory
* #type {string | undefined}
*/
const cwd = context.getCwd?.()
const relativeFilePath = filename.replace(cwd || '', '')
const fileInApiDirectory = /src\/.*api\//.test(relativeFilePath)
return {
/**
* #type {import('#typescript-eslint/utils/dist/ts-eslint').RuleFunction<import('#typescript-eslint/utils/dist/ts-estree').TSESTree.ArrowFunctionExpression>}
* #returns
*/
ArrowFunctionExpression(node) {
I have a js function:
/**
*
* #param {Object} obj function gets on param - an object
* #param {Number} obj.param1 - 1st num
* #param {Number} obj.param2 - 2nd num
*
* #returns {Number} - the result of the request
*/
const myFunc = ({ param1, param2 }) => {
return param1 * param2
}
After compiling it with babel I get:
/**
*
* #param {Object} obj function gets on param - an object
* #param {Number} obj.param1 - 1st num
* #param {Number} obj.param2 - 2nd num
*
* #returns {Number} - the result of the request
*/
var myFunc = (_ref) => {
var param1 = _ref.param1,
param2 = _ref.param2
return param1 * param2
}
At this point jsdoc is breaking because it is not connecting the jsdoc declaration to the function below anymore.
I also tried to use #function with #name but still no success.
I want to be able to see the relevant param type and comment when using the compiled version. Any idea how can I keep it consistent?
Thanks
I have a function that can accept a single number or an array of numbers and return back either a single result or an array of results. I cannot get VScode to return the proper type into the stored variable for intellisense.
I've already tried using some documentation patterns with JSDoc like the following:
/**
* Some Description
*
* #constructor
* #param {number} nums
* #returns {number}
*//**
* Some other Description for array version!
*
* #constructor
* #param {number[]} nums
* #returns {number[]}
*/
I have also tried the following but to no avail:
/**
* Some Description
* #param {number|number[]} nums
* #returns {number|number[]}
*/
This approach says that the variable can be either or and doesn't actually give a definite result.
/**
* Some Description
*
* #constructor
* #param {number} nums
* #returns {number}
*//**
* Some other Description for array version!
*
* #constructor
* #param {number[]} nums
* #returns {number[]}
*/
function addOne(nums) {
if (Array.isArray(nums))
return nums.map(n => n+1);
else
return nums + 1;
}
var a = addOne(1); // ::number -> Intellisense shows a is of type number CORRECT!
var b = addOne([ 1, 2 ]); // ::number -> Intellisense shows b as if it's of type number which is incorrect. It should be ::number[] which would be correct.
Basically, it should show var a; from the above example as type ::number and var b; as type ::number[]
I have an object that contains multiple methods and is a member of a class. How would I document this with JSDoc?
Here's my attempt. With this SomeClass#helperFunctions is documented, but both of it's methods are omitted.
/**
* #class SomeClass
* #param name
*/
var SomeClass = function(name) {};
/**
* #member SomeClass#helperFunctions
*/
SomeClass.prototype.helperFunctions = {
/**
* #method SomeClass#helperFunctions.doSomething
* #param {Array} arr
*/
doSomething: function(arr) {}
};
/**
* #method SomeClass#helperFunctions.doSomethingElse
* #param {Array} arr
*/
SomeClass.protype.helperFunctions.doSomethingElse = function(arr) {};
This is the best I could come up with.
I document methods of SomeClass#helperFunctions as globals then include them as properties of SomeClass#helperFunctions using links.
/**
* #class SomeClass
* #param {String} name
*/
var SomeClass = function(name) {};
/**
* #member SomeClass#helperFunctions
* #property {Function} doSomething [_doSomething]{#link _doSomething}
* #property {Function} doSomethingElse [_doSomethingElse]{#link _doSomethingElse}
*/
SomeClass.prototype.helperFunctions = {
doSomething: _doSomething,
doSomethingElse: _doSomethingElse
};
/**
* #function _doSomething
* #param {Array} arr
*/
_doSomething = function(arr) {};
/**
* #function _doSomethingElse
* #param {Array} arr
*/
_doSomethingElse = function(arr) {};
In my actual application SomeClass was also a module so it was written as:
/**
* #module path/to/SomeClass
*/
/**
* #class module:path/to/SomeClass
*/
var SomeClass = module.exports = function() {};
Then the links were written as {#link module:path/to/SomeClass~_doSomething} so it would link to it's spot on the module page instead of looking for them in Globals.
I use webstorm 10, and was trying ecmascript 6 with the following code:
/**
* Class Person
*/
class Person {
/**
* Constructor
* #param lastname
* #param firstname
* #param age
* #param sexe
*/
constructor(lastname, firstname, age, sexe) {
this.lastname = lastname;
this.firstname = firstname;
this.age = age;
this.sexe = sexe;
}
/**
* Return the name as string
* #returns {string}
*/
toString() {
return this.firstname + ' ' + this.lastname;
}
/**
* Return true if is an Adult
* #returns {boolean}
*/
isAdult() {
return this.age > 18;
}
/**
*
* #param {Person} person
* #returns {*}
*/
static isAdult(person) {
return person.isAdult();
}
}
What I am doing wrong that webstorm tell me that firstname and lastname in toString are unresolved variables, so age and as well isAdult() in the static method?
I bumped into the same problem. In order to fix it you have to supply the #class annotation. This way, it knows it's a class and treats properties as class properties, without warnings.
/**
* #class Person
*/
class Person {
...
You might also want to annotate the properties, like so
/**
* #class Person
* #property lastname {String}
* #property firstname {String}
* #property age {Number}
* #property sexe {String}
*/