Develop Reference

JSDOC on socket.io emit

If I have socketio function like this :
_sock.emit('app_version',appversion,(response)=>{
console.log(response)
})
and I want to put a proper JSDOC , explaining that appversion is a string, and response is a string, how do i write it ?
currently tried some combination like #param , or #property in WebStorm, yet Webstorm still don't recognize that appversion and response type.
Kindly help

JSDoc works best if you type things as you declare them, which doesn't work very well if you're doing things inline (such as using an inline arrow function. Try something like this, declaring and typing your variables and functions before using them:
// Use #type to indicate the type of the next following variable
/**
* #type {string}
*/
let appversion;
// Use #param to indicate the param type of the next following function
/**
* #param {string} response
*/
function doThing(response) {
console.log(response);
}
_sock.emit('app_version', appversion, doThing);

JSDoc3 does not generate hyperlinks to namespaces in NodeJS

I bet this is a stupid question but I somehow can't find the reason for this in any document I have found since this morning.
I am experienced in using JavaDoc but somehow even though the syntax of #link is the same, JSDoc3 simply does not generate hrefs to the related elements. I have tried out every possible way for the namespaces to link (also obviously wrong ones), but non of them changes the result a bit. I expected to receive a link by writing {#link #myFunction} or at least {#link MyClass#myFunction}, but neither of this created a hyperlink. Here is the code I have tested this with:
/**
* See {#link myOtherFunction} and [MyClass's foo property]{#link MyClass#foo}.
* Or look at {#link https://github.com GitHub}
*/
function myFunction(){};
/**
* See {#link #myFunction} or maybe {#link #myFunction()}
*/
function myOtherFunction() {};
I am generating it with ./node_modules/.bin/jsdoc ./* --configure ./conf.json and my default config file is:
{
"tags": {
"allowUnknownTags": true
},
"source": {
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"plugins": [],
"templates": {
"cleverLinks": true,
"monospaceLinks": false,
"default": {
"outputSourceFiles": true
}
}
}
(it makes no difference if I write "cleverLinks": false,)
This is how my output looks like:
So as one can see the URL is generated properly but the namespaces are not.
I am just badly confused since I can nowhere find a description that something must be done in order to generate hrefs to my namespaces. Additionally jsdoc says:
The {#link} inline tag creates a link to the namepath or URL that you specify. When you use the {#link} tag, you can also provide link text, using one of several different formats. If you don't provide any link text, JSDoc uses the namepath or URL as the link text.
which does not sound like there needs to be done anything in order to generate links to the namepaths.
And it also defines the syntax to be:
{#link namepathOrURL}
[link text]{#link namepathOrURL}
{#link namepathOrURL|link text}
{#link namepathOrURL link text (after the first space)}
My namepaths are okay as well since webstorm is able to resolve them directly.
What am I missing so badly?
Best regards,
Vegaaaa

I have found out my issue was related to the usage of JSDoc with CommonJS (NodeJS). After several hours of googling and trial and error I have managed to end up with how it working differently in NodeJS. I might play around with #inner and #instance but this resolves the question why JSDoc did not want to generate links for my NodeJS Code.
It is due to the fact that CommonJS's scope works differently to client side JS, which has one reason in the definition of NodeJS modules. Thus one need to tell JSDoc how to resolve a variable by adding the #module tag for a module and referencing to members of a module by resolving its relationship like {#link module:MODULE_NAME~instanceName}.
Here is an example with the corresponding generated html. Hope this helps someone running in the same issues like me.
Best regards,
Vegaaaa
/**
* #module lib
*/
/**
* #constructor
*/
var SomeClass = function () {
};
/**
* Some doc...
*/
var moduleFunction = function () {
/**
* #type {number}
*/
var innerVar = 0;
/**
* #type {number}
*/
this.instanceVar = 0;
/**
* #memberOf module:lib~moduleFunction
*/
function staticVar() {
console.log(0)
}
}
/**
* Link to this module (identified by #module lib in the beginning): {#link module:lib} <br/>
* Link to my constructor: {#link module:lib~SomeClass} <br/>
* Link to a module function: {#link module:lib~moduleFunction} <br/>
* Link to an instance variable of a module function: {#link module:lib~moduleFunction#instanceVar} <br/>
* Link to a inner variable within a module function: {#link module:lib~moduleFunction~innerVar} <br/>
* Link to a static variable within a module function: {#link module:lib~moduleFunction.staticVar} <br/>
*/
function documentedFunction(){}

Closure Compiler externs - Referencing a complex function

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.

Bad type annotation. Unknown type

I keep getting the warning mentioned above but can't figure out why. I've added deps.js and deps.js contains a reference to the type.
Here is the offending code:
goog.provide("MyCompany.MyApp.dom");
MyCompany.MyApp.dom.getArticleAmountInput_=function(){
return document.getElementById("articleAmount");
};
/**
* Gets the article amount input value
* #type {function(this:MyCompany.MyApp.dom):number} */
MyCompany.MyApp.dom.getArticleAmount=function(){
var tmp=this.getArticleAmountInput_();
return (tmp)?tmp.value():undefined;
};
In deps.js:
goog.addDependency('../../MyCompany/MyApp/dom.js', [ 'MyCompany.MyApp.dom'], []);
Code loads in html so it does find the class at runtime. Here is how I compile the code:
java -jar ../../compiler.jar \
--compilation_level=ADVANCED_OPTIMIZATIONS \
--formatting=PRETTY_PRINT \
--warning_level=VERBOSE \
--summary_detail_level=3 \
--js=MyCompany/MyApp/dom.js \
--js=closure/goog/deps.js \
--js_output_file=out.js
And it keeps giving me the warning:
WARNING - Bad type annotation. Unknown type MyCompany.MyApp.dom
[update]
Tried to leave out the goog.provide completely and leave out the js=closure/goog/deps.js when compiling and changed everything to lower case but keep getting the same warning on this code:
//goog.provide("mycompany.myapp.dom");
var mycompany={};
mycompany.myapp={};
mycompany.myapp.dom={};
mycompany.myapp.dom.getArticleAmountInput_=function(){
return document.getElementById("articleAmount");
};
/**
* Gets the article amount input value
* #type {function(this:mycompany.myapp.dom):number} */
mycompany.myapp.dom.getArticleAmount=function(){
var tmp=this.getArticleAmountInput_();
return (tmp)?tmp.value():undefined;
};
[update]
The thing is that when I add a typedef I get warnings that myapp.dom is never defined but when I let the code determine what the type is I get Bad type annotation.
Tried to add a typedef like so:
/**
* #typedef {{getArticleAmount:function(this:myapp.dom):?number}}
*/
myapp.dom;
But don't realy see why as goog.provide should create the myapp.dom and the compiler should know that.
[update]
I have created the following myapp.workflow from constructors. Now the compiler should recognize the type and Eclipse can code assist. Not sure if this is the way to do it but I'll try to re factor a small project.
Setting up the main types in types.js
// source: js/mmyapp/types.js
goog.provide("myapp.types");
/** #constructor */
var gooblediegoog=function(){};
/** #constructor */
gooblediegoog.prototype.WorkFlow=function(){};
/** #constructor */
gooblediegoog.prototype.Dom=function(){};
myapp.types=new gooblediegoog();
A file that isn't used at all in my code but tells Eclipse how to auto complete:
// source: js/myapp/forCodeAssist.js
/** #const {boolean} */
var ALLWAYSFALSE=false;
if(ALLWAYSFALSE){
/**needed for Eclipse autocomplete
* #constructor
*/
var MyApp=function(){};
MyApp.prototype.types=new gooblediegoog();
Window.prototype.myapp=new MyApp();
MyApp.prototype.workflow=new myapp.types.WorkFlow();
MyApp.prototype.dom=new myapp.types.Dom();
}
An implementation of workflow:
// source: js/myapp/workflow.js
goog.provide("myapp.workflow");
goog.require("myapp.types");
goog.require("myapp.dom");
/** #returns number|undefined */
myapp.types.WorkFlow.prototype.createOrder=function(){
return myapp.dom.getArticleAmout();
};
myapp.workflow=new myapp.types.WorkFlow();
window['console'].log(myapp.workflow.createOrder());
This can be converted to a myapp.workflow.createOrder=... syntax by replacing myapp.types.WorkFlow.prototype with myapp.workflow, removing myapp.workflow=new myapp.types.WorkFlow() and removing the goog.require("myapp.types"). Maybe this can be automated in the build/compile process if needed.
I am not sure if creating a single object with the help from a constructor function is much more expensive than just having goog.require create myapp.workflow and adding properties to it as I used to do (and as it's done in closure library).

Anonymous types (namespaces or singletons) don't have specific types in Closure-compiler and cannot be used as a type name in an annotation. Only constructors and interfaces can be used as new type names. (typedefs can be used but are really just shorthand annotations)
In many cases the compiler will correctly infer the types and you will not need to annotate it. In your specific case, it looks like the problem is your use of the this keyword. Using the this keyword in a static object / namespace is dangerous and not supported. The compiler will raise a warning. While you can suppress the warning with a #this annotation, that is not the correct action here as you are not specifically specifying the this reference by using .call or .apply.
The solution is to use the full object name:
/**
* Gets the article amount input value
*/
mycompany.myapp.dom.getArticleAmount=function(){
var tmp=mycompany.myapp.dom.getArticleAmountInput_();
return (tmp)?tmp.value():undefined;
};
For the full technical details, reference the This this is your this post.

Best way to document anonymous objects and functions with jsdoc

Edit: This is technically a 2 part question. I've chosen the best answer that covers the question in general and linked to the answer that handles the specific question.
What is the best way to document anonymous objects and functions with jsdoc?
/**
* #class {Page} Page Class specification
*/
var Page = function() {
/**
* Get a page from the server
* #param {PageRequest} pageRequest Info on the page you want to request
* #param {function} callback Function executed when page is retrieved
*/
this.getPage = function(pageRequest, callback) {
};
};
Neither the PageRequest object or the callback exist in code. They will be provided to getPage() at runtime. But I would like to be able to define what the object and function are.
I can get away with creating the PageRequest object to document that:
/**
* #namespace {PageRequest} Object specification
* #property {String} pageId ID of the page you want.
* #property {String} pageName Name of the page you want.
*/
var PageRequest = {
pageId : null,
pageName : null
};
And that's fine (though I'm open to better ways to do this).
What is the best way to document the callback function? I want to make it know in the document that, for example, the callback function is in the form of:
callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus)
Any ideas how to do this?

You can document stuff that doesnt exist in the code by using the #name tag.
/**
* Description of the function
* #name IDontReallyExist
* #function
* #param {String} someParameter Description
*/
/**
* The CallAgain method calls the provided function twice
* #param {IDontReallyExist} func The function to call twice
*/
exports.CallAgain = function(func) { func(); func(); }
Here is the #name tag documentation. You might find name paths useful too.

You can use #callback or #typedef.
/**
* #callback arrayCallback
* #param {object} element - Value of array element
* #param {number} index - Index of array element
* #param {Array} array - Array itself
*/
/**
* #param {arrayCallback} callback - function applied against elements
* #return {Array} with elements transformed by callback
*/
Array.prototype.map = function(callback) { ... }

To compliment studgeek's answer, I've provided an example that shows what JsDoc with Google Closure Compiler lets you do.
Note that the documented anonymous types get removed from the generated minified file and the compiler ensures valid objects are passed in (when possible). However, even if you don't use the compiler, it can help the next developer and tools like WebStorm (IntelliJ) understand it and give you code completion.
// This defines an named type that you don't need much besides its name in the code
// Look at the definition of Page#getPage which illustrates defining a type inline
/** #typedef { pageId : string, pageName : string, contents: string} */
var PageResponse;
/**
* #class {Page} Page Class specification
*/
var Page = function() {
/**
* Get a page from the server
* #param {PageRequest} pageRequest Info on the page you want to request
*
* The type for the second parameter for the function below is defined inline
*
* #param {function(PageResponse, {statusCode: number, statusMsg: string})} callback
* Function executed when page is retrieved
*/
this.getPage = function(pageRequest, callback) {
};
};

#link can add inline links to methods and classes.
/**
* Get a page from the server
* #param {PageRequest} pageRequest Info on the page you want to request
* #param {function} callback Function executed when page is retrieved<br />
* function({#link PageResponse} pageResponse,{#link PageRequestStatus} pageRequestStatus)
*/
this.getPage = function (pageRequest, callback) {
};
Not ideal, but it gets the job done.

The Google Closure Compiler Annotations has Type Expressions for this which includes the ability to indicate type for specific arguments, return type, and even this. Many libraries are looking at following the Google Closure Compiler Annotations, because they want to use it to shrink their code. So it's got some momentum. The downside is I don't see a way to give the description.
For providing the description perhaps the JSDoc Toolkit Parameters With Properties approach would work (look at the bottom of the page). It's what I am doing right now. The JSDoc Toolkit is prepping to start work on V3, so feedback there might be good.

You could use #see to link to another method within the same class. The method would never be used, it would just be there for documentation purposes.
/**
* #class {Page} Page Class specification
*/
var Page = function() {
/**
* Get a page from the server
* #param {PageRequest} pageRequest Info on the page you want to request
* #param {function} callback Function executed when page is retrieved
* #see #getPageCallback
*/
this.getPage = function (pageRequest, callback) {
};
/**
* Called when page request completes
* #param {PageResponse} pageResponse The requested page
* #param {PageRequestStatus} pageRequestStatus Status of the page
*/
//#ifdef 0
this.getPageCallback = function (pageResponse, pageRequestStatus) { };
//#endif
};
If you are using some kind of build system, the dummy method could easily be omitted from the build.

hope I'm not too late on this topic, but you can do something like this
/**
* Get a page from the server
* #param {PageRequest} pageRequest
* #param {(pageResponse: PageResponse, pageRequestStatus: PageRequestStatus) => void} callback
*/
this.getPage = function(pageRequest, callback) {}
the downside of this approach is that you can't document what each of the arguments does.