How can I refer to a complex function type with the Google closure compiler and not an instance of the constructor function?
externs.js - Externs for CoolLibrary.matchSomething
/** #externs */
/** #const */
const CoolLibrary = {};
/**
* #param {!Object} object The object to inspect.
* #param {!Object} source The object of property values to match.
* #param {!function(!Object): !Object} customizer The function to customize
* comparisons.
* #return {boolean} Returns `true` if `object` is a match, else `false`.
* #constructor
*/
CoolLibrary.matchSomething = function(object, source, customizer) {};
/**
* #param {string} src
* #return {!Object}
*/
function require(src) {}
foo.js - application code
goog.module('foo');
const isMatchWith = /** #type {!CoolLibrary.matchSomething} */ (require('coollibrary.matchsomething'));
const foo = isMatchWith({}, {}, (val) => {});
I'm invoking it like so:
java -jar closure-compiler-v20161201.jar --js=foo.js --externs=externs.js --new_type_inf
Here's a runnable version at the Closure Compiler Debugger
It errors with:
foo.js:3: WARNING - Bad type annotation. Unknown type Lodash.isMatchWith
const isMatchWith = /** #type {!Lodash.isMatchWith} */ (require('lodash.ismatchwith'));
^
0 error(s), 1 warning(s), 72.7% typed
It works if I use #typedef but that loses most of the information. Is there a better way to add type information than using typedef like below?
/** #typedef {function(!Object, !Object, function(!Object):!Object):boolean} */
CoolLibrary.matchSomething;
Function definitions are not type names. You can use a typedef to prevent retyping this data if you import the function it in multiple places. However, if you only import the information in a single place, then a typedef would be overkill.
For a single import, you would simply duplicate the function annotation in the type cast at your require call.
const isMatchWith =
/** #type {function(!Object, !Object, function(!Object):!Object):boolean} */
(require('lodash.ismatchwith'));
The compiler handles these cases for you when module bundling is used, but that requires all of the source files to be compatible with the compiler and provided as part of the compilation. This is not currently possible for an external library.
Related
I have several modules that all act the same way and export several functions inside of an object, like so:
module.exports = {
a:function(paramA,paramB) {
return 1;
},
b:function(paramC,paramD) {
return 'a';
}
}
They all follow the same schema (take these parameters, do things, and return this type). I'd like to be able to document all these files within the same file, so that documentation isn't repeated everywhere. The problem I'm running into is that if I create a #typedef with these functions specified, it is ignored if done like so:
/**
* #typedef {Object} myModuleType
* #property {functionType} a
*/
/**
* #module A
* #type {myModuleType}
*/
module.exports = {}
And if I create an interface, it complains that the methods are not implemented if done like so:
/**
* #interface myModuleType
*/
/**
* #function
* #name myModuleType#a
* #param paramA
* #param paramB
* #return {number}
*/
/**
* #module A
* #implements {myModuleType}
*/
module.exports = {}
Any ideas on how to get this to work?
So the original #type annotation actually works, it just doesn't autocomplete as it should in WebStorm after being documented.
This is being tracked at YouTrack for WebStorm as to when it will be fixed.
Edit: As of 12/18/2017, this has been fixed in a recent build of WebStorm and should hit the main branch soon.
I'm trying to document the input parameters to a function in javascript, but I can't work out how to do it in jsdoc.
I've looked at the jsdoc documentation which suggests that using the #callback comment is what's required, but Visual Studio Code (vscode) doesn't highlight it as per the screenshot.
The intellisense for the location parameter shows that it's type any rather than of type locator (a function with a parameter of id which returns a Location).
Example code which shows a function calling a function passed as a parameter:
class Location {
constructor(position, count) {
this.position = position;
this.count = count;
}
}
const items = {
'USB Cable': new Location('Desk Drawer', 123),
Keyboard: new Location('Desk Surface', 1),
};
/**
* A locater.
* #param {string} id
* #returns {Location}
*/
const locaterA = id => items[id];
/**
* Finds the item by its unique id.
* #callback locater
* #param {string} id
* #returns {Location}
*/
/**
* Attempt to find the item with the given locater.
* #param {string} id
* #param {locater} locater
*/
const locate = (id, locater) => locater(id);
const result = locate('USB Cable', locaterA);
console.log(result);
Is this a problem with what I'm doing, vsdoc not supporting the use case, or vscode not supporting it?
Edit: vscode seems to be supporting #callback starting from TypeScript 2.9
Vscode's IntelliSense doesn't support #callback. It's being tracked here: https://github.com/Microsoft/TypeScript/issues/7515.
As a convenient workaround you can use #typedef:
/**
* Finds the item by its unique id.
* #typedef {function(string): Location} Locater
*/
/**
* Attempt to find the item with the given locater.
* #param {string} id
* #param {Locater} locater
*/
const locate = (id, locater) => locater(id);
It looks like you're using it correctly, per JSDoc itself. However, it looks like Visual Studio may only support a limited subset of JSDoc, which doesn't include #callback: https://msdn.microsoft.com/en-us/library/mt162307.aspx
I don't have Visual Studio handy, but you might try the Google Closure style, which is to do it like this:
#param { function(string) : number } locator
This says that it's a function that takes a string, and returns a number.
You can find that documentation here: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler (search for "Function Return Type" to jump to the relevant section).
I've noticed with JetBrains stuff at least, that it supports that syntax.
Since I was sent here from reddit concerning the documentation of an async function passed to another func, I answer here even if it's not exactly the op's question.
It's enough to document the return of the function with a Promise, in ES6 :
/**
* #param {(input: any) => Promise<any>} asyncFunctionAsParam - async function given
*/
const myfunc = (asyncFunctionAsParam) => {
// ...
}
I have a JavaScript function getting some parameters including object types. However, one property of a parameter, which is an object, will be used as deprecated. I would like to indicate this situation in the documentation, however I don't know how to use #param tag with #deprecated. Consider the example below:
/**
* This function does something.
*
* #name myFunction
* #function
* #since 3.0
* #param {function} [onSuccess] success callback
* #param {function} [onFailure] failure callback
* #param {object} [options] options for function
* #param {string} [options.lang] display language
* #param {string} [options.type] type of sth
*/
this.myFunction= function (onSuccess, onFailure, options) {
//do something
}
I want to deprecate "type" property of "options" object. How can I do that, or can I?
Official JSDoc documentation does not indicate that the #deprecated tag can be used for deprecating anything else than an entire symbol.
The #deprecated tag can be used to document that for example a function as a whole has been deprecated.
/**
* #deprecated since version 2.0.0
*/
function old () {
}
You can of course, as #Droogans said in the comments, add something like deprecated: in front of the #param description. If a developer somehow still ends up using the deprecated feature, you could implement a warning of some sorts.
/**
* #param {string=} bar - Deprecated: description
*/
function foo (bar) {
if (bar) {
console.warn('Parameter bar has been deprecated since 2.0.0')
}
}
A suggestion is using typescript, like so:
function test(
options: {
/**
* #deprecated use newName instead
*/
name?: string,
newName?: string
}) {
}
I am trying to properly annotate all my Javascript code and am still a beginner in this field.
I get objects from a server call that are directly in json. Those objects are passed to functions and I call members directly. It obviously is very error prone while obfuscating so I am trying to annotate everything properly.
My understanding is that (i) I should create a class for this object even though it is never created directly with new and (ii) I should be careful with member names since they are fixed by the server response and should not be changed (or should be aliased beforehand).
I have two questions: are my asumptions correct ? how to do the annotation based on that.
Here is a sample code to illustrate
$.get("url.php", function(data) {
process(data);}, "json"); // <= returns {"a":"abc","b":1}
function process(data) {
$("#someElement").html(data.a + data.b);
}
Here is the class I was planning on creating for closure compilation purposes
/**
* The object that is sent back from the server
* #constructor
*/
function ServerResponse() {
/** #type {string} a */
this["a"] = "";
/** #type {number} b */
this["b"] = 0;
}
Here is the annotation for my process function
/**
* Process data from the server
* #param {ServerResponse} data: the Object sent back from the server
*/
Is my annotation correct? Is it robust to obfuscation?
Thanks a lot for your help
If you quote property names, you need to quote them consistently at every usage. If you haven't see this, you should read:
https://developers.google.com/closure/compiler/docs/api-tutorial3
So that your first snippet would be:
function process(data) {
$("#someElement").html(data['a'] + data['b']);
}
If you are trying to avoid quoting or if you would like the compiler to type check the usage of the properties (quoted properties references are not checked), you should define an extern file to include with the compilation of your source:
/**
* #fileoverview
* #externs
*/
/** #interface */
function ServerResponse() {}
/** #type {string} */
ServerResponse.prototype.a;
/** #type {number} */
ServerResponse.prototype.b;
I am using jsdoc-toolkit with the namespace library of Mike Koss. The code looks like this
namespace.module('a.b', // this is the namespace
// #param {Object} exports visible classes within this namespace
// #param {function} required other namespaces
function (exports, require) {
var entityBase = require("a.base");
var util = require("a.util");
// #class BlaBla
// #constructor
// #property {String} ..
// #property {String} ..
// #property {String} ..
// #property {..} ....
// #param {Array} ...
// #param {X} [optionalParam]
exports.MyClass = function (...) {
Creating documentation I get the following message and no documentation is created at all for this class.
>> WARNING: Trying to document exports.MyClass without first documenting exports.
I have tried to overcome the issue with the param lines - no success.
// #param {Object} exports visible classes within this namespace
// #param {function} required other namespaces
function (exports, require) {
Any idea how to overcome the issue?
I have switched to JsDoc 3 (https://github.com/micmath/jsdoc#readme). This support modules and hence the above namespace library.