When I use the #package annotation and then try to access it from a file in another directory I receive no warning on compiling. The compiler is given a warning_level argument of 'VERBOSE' (and I receive warnings for #private violations).
See https://developers.google.com/closure/compiler/docs/js-for-compiler
For example:
In ns/pkg/foo.js
/**
* #constructor
*/
ns.pkg.Foo = function(){}
/**
* #package
*/
ns.pkg.Foo.prototype.modify = function() {}
In ns/view.js
/**
* Factory method
*/
ns.View.create = function() {
var myFoo = new ns.pkg.Foo();
myFoo.modify(); // ***no compiler error***
//...
}
Am I missing a compiler flag or misunderstanding closure docs? Or is this a bug in the compiler?
Related
I have a module that is going to be exported to npm to be used in other projects and for others that could use it to enjoy the library as well.
The code works, if you know the methods and properties you can call them and they work.
However (in my case) Intellisense isn't picking them up whereas other npm modules do (i.e. ws)
I published the module/library to npm and installed it into my new project (https://i.imgur.com/mU7hA2H.png for reference on the intellisense I am seeing)
Now my question is as follows, am I missing a step in order to get this to work so that developers see the available methods and properties?
I've tried looking into other modules and see how they did it, but from what I can tell this should show up in intellisense, but it doesn't...
'use strict';
class ParkDS {
constructor() {
var c = require('./Config/Config');
var d = require('./DataSource/DataSource'));
this.config = new c();
this.datasource = new d();
this.certificate = {
Cert: "",
Key: ""
};
}
/**
* #returns {Object}
* #public
* */
get Config() {
return this.config;
}
/**
* #returns {Object}
* #public
* */
get DataSource() {
return this.datasource
}
/**
* #returns {Object}
* #public
* */
get Certificate() {
return this.certificate;
}
/**
* #public
* */
Test() {
console.log("test");
}
/**
* #public
* */
Start() {
// Code to start all services
}
/**
* #public
* */
Stop() {
// Code to stop all services
}
}
module.exports = ParkDS;
I expect the intellisense to show Config, DataSource, and Cerfificate as Properties, and Test, Start, Stop as Methods
Thanks to the answer found here:
https://stackoverflow.com/a/19336366/592495
My JavaScript documentation is well-organized and well-formatted. Each namespace is a "parent" of methods contained within. However, navigation is not quite as granular as I would like.
After compiling/rendering using the node.js tool via a simple command (jsdoc file1.js file2.js), the docs are generated into a default template. This default template displays my namespaces in the sidebar navigation, but it does NOT show methods that each contains.
You can fake a list of methods by adding the #class directive to each method, but as we know, they are not really classes.
I would love to see a sidebar navigation like this:
My Project
- namespace 1
- method.a
- method.b
- method.c
-namespace 2
- method.d
- method.e
Any direction to documentation I have overlooked would be greatly appreciated.
[edit to add:]
Upon experimentation, #class does almost exactly what I want but with some exceptions:
It lists classes above namespaces. I don't like that since the namespaces are the "parents" as it were.
JavaScript doesn't have classes in that sense. Not ones that are called "classes" with that nomenclature. It creates a weird disconnect when reading the document to see a list of "classes".
It adds the "new" operator automagically. Not all of the methods have constructors... you can see the problem!
[edit: sample code]
So here's the current structure. Before I annotate it with JSDoc comments, here's the basic approach:
var app = app || {};
app.utils = {
whizbang: function() {},
geegolly: function() {}
};
app.render = {
thestuff: function(params) {},
thethings: function(params) {}
}
}
So, using object literal notation, the top level is a "namespace" for the whole application, but within there are sub-namespaces for different purposes. Here, I have a sub-namespace specific to utilities, and another one specific to rendering. Each can have properties, but more importantly they each contain functions. It is these functions which should appear in the sidebar. Now to flesh it out with my current pattern for JSDoc:
/**
* #file MyApp.js This is an awesome description of MyApp.js
*
* #version 0.1
* #author Greg Pettit
* #copyright 2015
*
*/
/**
* Description of my main namespace!
*
* #namespace app
*/
var app = app || {};
/**
* This is a description of my sweet utilities namespace!
*
* #memberof app
* #type {object}
* #namespace app.utils
*/
app.utils = {
/**
* app.utils.whizbang is an awesome function with magical powers. I sure wish
* it would appear in the sidebar as a member of app.utils!
*
* #memberof app.utils
* #method whizbang
*
* #param {method} [successCallback] Method invoked on successful attempt.
* #param {method} [errorCallback] Method invoked on unsuccessful attempt.
*
*/
whizbang: function(successCallback, errorCallback) { // do utility stuff! }
}
/**
* This is a description of the best rendering namespace ever.
*
* #memberof app
* #type {object}
* #namespace app.render
*/
app.render = {
/**
* app.render.thethings renders the things! I wish it would render to the sidebar...
*
* #memberof app.render
* #method thethings
*
* #param {method} node The node to which thethings are rendered
*
*/
thethings: function(node) { // do rendering stuff! }
}
Have you tried using the #lends tag? An example of your code and doc comments would be helpful here.
Since I don't know what your code looks like, I'll just give an example of how I use JSDoc with our in-house framework, which has lots of idiosyncracies (hey, I didn't write it, I just have to use it).
Just to give some context, we have a context object that can create apps and modules (apps are just modules with a start method):
/** #namespace MyApp */
var MyApp = context.app('myApp').use('module1', 'module2', 'underscore');
We have a dependency injection system for backbone that uses an angular-style pattern for expressing dependencies:
/**
* The constructor for MyModel
* #memberof MyApp
* #param {object?} attrs
* #param {object?} options
* #param {AppUtils} appUtils
* #constructor
*/
MyApp.MyModel = function(attrs, options, appUtils) {
this.options = options;
this.utils = appUtils;
}
// This is injected by the dependency resolver at instantiation time
// No additional JSDoc comments are necessary, it actually gets this right
MyApp.MyModel.prototype = {
idAttribute: 'customId',
defaults: {
customId: '',
name: '',
birthday: null
}
};
// Registers MyModel with the IOC container as 'myModelName'
MyApp.model('myModelName', [
'attrs',
'options',
'appUtils'
MyApp.MyModel
]);
And then a different file can have an instance of myModelName injected by adding it to that dependency array at the bottom.
Funny thing is, JSDoc actually does a pretty good job of understanding that particular arrangement, as long as I don't try to get too fancy... but the following pattern is apparently too confusing for it:
/**
* #memberof MyApp
* #param {MyApp.MyModel} myModel
* #param {urlParser} urlParser
* #constructor
*/
MyApp.SomeService = function(myModel, urlParser) {
return {
foo: function() {
//whatever
},
bar: function() {
//whatever
}
};
};
MyApp.service('someModuleName', [
'myModelName',
'urlParser',
MyApp.SomeService
]);
The only thing that I've found that gives me anything close to the desired output is using the #lends tag to tell JSDoc that a particular object/property/method is "lended" as a different property. For example, to document the attributes property of a backbone model (which is ostensibly defined by its defaults property), we do this:
MyApp.MyModel.prototype = {
idAttribute: 'customId',
/** #lends MyApp.MyModel.prototype.attributes */
defaults: {
customId: '',
name: '',
birthday: null
}
};
And for that case where the service is returning an object, the only way we've found to get those object properties documented is like this:
/**
* #memberof MyApp
* #param {MyApp.MyModel} myModel
* #param {urlParser} urlParser
* #constructor
*/
MyApp.SomeService = function(myModel, urlParser) {
/** #lends MyApp.SomeService.prototype */
return {
foo: function() {
//whatever
},
bar: function() {
//whatever
}
};
};
I have no idea if any of that was useful, but maybe it'll give you some ideas for things you could try with #lends. If you can provide some example code, I can possibly give you a more useful answer.
I'm trying to find a way to document AMD modules using JSDoc3.
/**
* Module description.
*
* #module path/to/module
*/
define(['jquery', 'underscore'], function (jQuery, _) {
/**
* #param {string} foo Foo-Description
* #param {object} bar Bar-Description
*/
return function (foo, bar) {
// insert code here
};
});
Sadly none of the patterns listed on http://usejsdoc.org/howto-commonjs-modules.html work for me.
How can I generate a proper documentation that lists the parameters and return value of the function exported by the module?
As of the latest stable version (3.2.2) I do not think there is a way to do use jsdoc to produce documentation that will show that the module itself accepts parameters and returns some value. The closest I can come to the ideal is this:
/**
* Module description.
*
* #module path/to/module
*/
define(['jquery', 'underscore'], /** #lends module:path/to/module */
function (jQuery, _) {
/**
* The following function documents the parameters that the module
* takes and its return value. Do not call as
* <code>module.self(...)</code> but as <code>module()</code>.
*
* #param {string} foo Foo-Description
* #param {object} bar Bar-Description
*/
return function self(foo, bar) {
// insert code here
};
});
The generated documentation for the module will have an extra inner function named self.
The following seems to generate a result which looks quite acceptable:
/**
* Module description
*
* #module path/to/module
*/
define(['jquery', 'underscore'], function (jQuery, _) {
/**
* Description for function.
*
* #param {string} foo Foo-Description
* #param {object} bar Bar-Description
*/
var exports = function () {
// insert code here
};
return exports;
});
Which describes the module and the function with something like:
require("path/to/module")(foo, bar)
That's not perfect for AMD modules but I think the reader of the documentation is able to understand what the module exports.
I'm having an issue with closure compiler where it's not enforcing strict type checks for some strange reason. It correctly checks type safety when setting a variable where it's declared, but is failing to throw an type error when passing an object.
/**
* #public
* #param x {number}
*/
SomeClass.prototype.setterMethod = function(x) {
this.var1 = x;
};
var a = new SomeClass();
a.setterMethod({}); // SHOULD THROW AN ERROR!!!!!!
Why isn't closure compiler enforcing type safety here? It correctly functions if I declare the variable:
this.var1 = {}; // correctly throws an error
However it is not enforcing strict type safety checks on function parameters, or when setting the class member variable outside of the member declaration. I've posted the full code and output below. Is there a way to force closure to force these types of checks? Or am I doing something wrong here?
// ==ClosureCompiler==
// #compilation_level ADVANCED_OPTIMIZATIONS
// #warning_level VERBOSE
// #output_file_name default.js
// ==/ClosureCompiler==
/**
* #class SomeClass
* #constructor
*/
function SomeClass() {
/**
* #protected
* #type {number}
*/
this.var1;
};
/**
* #public
* #param x {number}
*/
SomeClass.prototype.setterMethod = function(x) {
this.var1 = x;
};
/**
* #public
* #returns {number}
*/
SomeClass.prototype.getterMethod = function() {
return this.var1;
};
/**
* #type {SomeClass}
*/
var a = new SomeClass();
a.setterMethod({});
console.log(a.getterMethod());
// output: -- NO WARNINGS!!!!
// var a=new function(){};a.a={};console.log(a.a);
There are two issues occurring:
The Closure-compiler web service runs in a type of "demo" mode and assumes all undeclared variables are external. There is currently no way to disable this. Testing with the command line compiler doesn't show the same issues.
Your JSDoc paramater annotation is not correct. It should be #param {number} x (you have the type and name reversed).
I am trying to understand the JSDoc style for documenting JavaScript that is used with the JavaScript Closure Compiler. I have the JavaScript code below
// ==ClosureCompiler==
// #compilation_level ADVANCED_OPTIMIZATIONS
// ==/ClosureCompiler==
(function(){
/**
* #type Array.<string>
* #private
*/
var sb = [];
/**
* #const
* #type{{append: function(string): SingletonStringBuffer, toString: function(): string}}
*/
window['SingletonStringBuffer'] = {
/**
* #param {string} text
* #return {SingletonStringBuffer}
*/
append: function(text){
sb.push(text);
return SingletonStringBuffer;
},
/**
* #return {string}
*/
toString: function(){
return sb.join("");
}
};
}());
When I do an advanced compile on this code I am receiving 2 warnings.
JSC_TYPE_PARSE_ERROR: Bad type annotation. Unknown type SingletonStringBuffer at line 10 character 35
* #type{{append: function(string): SingletonStringBuffer, toString: function()...
^ JSC_TYPE_PARSE_ERROR: Bad type annotation. Unknown type SingletonStringBuffer at line 15 character 11
* #return {SingletonStringBuffer}
^
The function append returns a deference to the encapsulating object. The variable that it is returning ,SingletonStringBuffer, is declared... so I am not sure what is wrong or how to correct it.
You haven't created a named type as far as the compiler is concerned. For this case, I would expect you to create an interface:
/** #interface */
function StringBuffer() {
}
/**
* #param {string} text
* #return {StringBuffer}
*/
StringBuffer.prototype.append;
etc
This can be declared either in the code (if you are using advanced mode it will be stripped) or in your extern files (if you want the type without the code in simple mode).
You can then use it like so (in your case):
(function(){
/**
* #type Array.<string>
* #private
*/
var sb = [];
/**
* #const
* #type {StringBuffer}
*/
window['SingltonStringBuffer'] = {
/**
* #param {string} text
* #return {StringBuffer}
*/
append: function(text){
sb.push(text);
return SingltonStringBuffer;
},
/**
* #return {string}
*/
toString: function(){
return sb.join("");
}
};
}());
singletons work differently in closure. I have not seen an explicit annotation for it, but the compiler (in advanced mode) has some understanding of certain built-in functions
Singletons would be declared via the goog.addSingletonGetter function, here is a code sample
/**
* #constructor
* #extends {path.to.BaseClass}
*/
path.to.MyClass = function() {
goog.base(this);
};
goog.inherits(path.to.MyClass, path.to.BaseClass);
goog.addSingletonGetter(path.to.MyClass);
and that be it.
PS
you are getting the bad annotation because {SingltonStringBuffer} is never declared as a class.
PPS.
Some rambling on post the fact.
I suspect (but this is untested) that making the constructer private might work. Notice the trailing underscore in the example
/**
* #private -> NOTE THIS IS IN NO WAY VERIFIED
* #constructor
* #extends {path.to.BaseClass}
*/
path.to.MyClass_ = function() {
goog.base(this);
};
goog.inherits(path.to.MyClass, path.to.BaseClass);
goog.addSingletonGetter(path.to.MyClass);