I am currently using this:
/** #type {TagsLevel} */
export let list;
/** #type {string} */
export let tagListName;
/** #type {string | null} */
let srcTag = null;
/** #type {number | null} */
let srcTagNum = null;
/** #type {number | null} */
let srcLevelNum = null;
It's not very clear.
I wish I could use it that way:
/** #type {TagsLevel} */
/** #type {string} */
export let list;
export let tagListName;
/** #type {string | null} */
/** #type {number | null} */
/** #type {number | null} */
let srcTag = null;
let srcTagNum = null;
let srcLevelNum = null;
This should work identically to the previous code.
Is there a JSDoc syntax that enables something like this?
If not, I would like to know where to make the suggestion that support for such a case be introduced.
WHY THIS?
I am following the syntax of the function - #param. It's not identical, but it's very similar:
// Parameters may be declared in a variety of syntactic forms
/**
* #param {string} p1 - A string param.
* #param {string=} p2 - An optional param (Google Closure syntax)
* #param {string} [p3] - Another optional param (JSDoc syntax).
* #param {string} [p4="test"] - An optional param with a default value
* #returns {string} This is the result
*/
function stringsStringStrings(p1, p2, p3, p4) {
// TODO
}
The alternative - this:
/** #type {TagsLevel} */ export let list;
/** #type {string} */ export let tagListName;
/** #type {string | null} */ let srcTag = null;
/** #type {number | null} */ let srcTagNum = null;
/** #type {number | null} */ let srcLevelNum = null;
But it's not very clear either, and it makes the line very long.
I do have following Errors when js file is minified
/* Minification failed. Returning unminified contents.
(36307,7-8): run-time error JS1010: Expected identifier: .
(36307,7-8): run-time error JS1195: Expected expression: .
(36817,7-8): run-time error JS1010: Expected identifier: .
(36817,7-8): run-time error JS1195: Expected expression: .
(36820,7-8): run-time error JS1010: Expected identifier: .
(36820,7-8): run-time error JS1195: Expected expression: .
*/
The JavaScript file script file below,
However I found the JavaScript that contains "module.export"
will not be minified and I also use
online tool
for minification, but the minified file does not contain "module.export"
and it is removed
during minification. Any help how to sort the minification problem of JavaScript file contain module.export
(function e(t, n, r) {
module.exports = FilterCSS;
}, {
"./default": 7,
"./parser": 9,
"./util": 10
}], 7: [function(require, module, exports) {
/**
* cssfilter
*
* #author ??<leizongmin#gmail.com>
*/
function getDefaultWhiteList() {
// ??????:
// true: ?????
// Function: function (val) { } ??true???????,?????????
// RegExp: regexp.test(val) ??true???????,?????????
// ??????????????
var whiteList = {};
whiteList['align-content'] = false; // default: auto
whiteList['align-items'] = false; // default: auto
*
*
#param {
String
}
name
*
#param {
String
}
value
*
#param {
Object
}
options
*
#return {
String
}
*/
function onAttr(name, value, options) {
// do nothing
}
/**
* ???????????????
*
* #param {String} name
* #param {String} value
* #param {Object} options
* #return {String}
*/
function onIgnoreAttr(name, value, options) {
// do nothing
}
var REGEXP_URL_JAVASCRIPT = /javascript\s*\:/img;
/**
* ?????
*
* #param {String} name
* #param {String} value
* #return {String}
*/
function safeAttrValue(name, value) {
if (REGEXP_URL_JAVASCRIPT.test(value)) return '';
return value;
}
exports.whiteList = getDefaultWhiteList();
exports.getDefaultWhiteList = getDefaultWhiteList;
exports.onAttr = onAttr;
exports.onIgnoreAttr = onIgnoreAttr;
exports.safeAttrValue = safeAttrValue;
}, {}], 8: [function(require, module, exports) {
/**
* cssfilter
*
* #author ??<leizongmin#gmail.com>
*/
var DEFAULT = require('./default');
var FilterCSS = require('./css');
/**
* XSS??
*
* #param {String} css ????CSS??
* #param {Object} options ??:whiteList, onAttr, onIgnoreAttr
* #return {String}
*/
function filterCSS(html, options) {
var xss = new FilterCSS(options);
return xss.process(html);
}
// ??
exports = module.exports = filterCSS;
exports.FilterCSS = FilterCSS;
for (var i in DEFAULT) exports[i] = DEFAULT[i];
// ???????
if (typeof window !== 'undefined') {
window.filterCSS = module.exports;
}
}, {
"./css": 6,
"./default": 7
}], 9: [function(require, module, exports) {
/**
* cssfilter
*
* #author ??<leizongmin#gmail.com>
*/
var _ = require('./util');
Try like this:
['module'].exports = FilterCSS;
Also this:
[module].exports = FilterCSS;
It worked for me, but no idea why.
Before this epiphany, I had solve similar issues with global variables, using something like this:
window['module'].exports=......
But, at least in my case, module was no global.
No idea how I came up with this, and less idea how it worked. I'm new with javascript.
I have come across what appears to be a bug in how PhpStorm interprets #typedef in JSDoc3 when used with #namespace. I receive the following warning..
Argument type item is not assignable to parameter type item
..when b(item); is called below:
(function() {
'use strict';
/**
* #namespace myNamespace
*/
/**
* #typedef {Object} item
* #property {string} key
* #property {string} value
*/
/**
* #function a
* #param {item} item
* #returns {item}
*/
function a(item) {
item.key = 'key';
item.value = 'value';
return item;
}
/**
* #function b
* #memberOf myNamespace
* #param {item} item
* #returns {item}
*/
function b(item) {
item.key = 'key';
item.value = 'value';
return item;
}
/** #type item */
var item = {
key: 'hello',
value: 'world'
};
a(item);
b(item);
})();
I only receive this warning on function b because of the #memberOf definition and when I remove it the warning disappears. Any ideas what would cause this?
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'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) {
};