I try to use @callback in many way but I never obtain a documentation which use the way I expect when I use JSDoc API to generate documentation.
1. The code I expected must be used
With the following code in callback-jsdoc-test.js:
/**
* The foo function for example.
* function foo
* @param {Object} bar - The baz parrameters.
* @param {foo~next} next - What next after foo process ?
*/
function foo(bar, next) {
if (bar === "baz") {
return next(new Error("no baz allowed"));
}
bar += bar;
/**
* @callback foo~next
* @param {(Object|null)} err - return error object in case of error, else null.
* @param {(Object|undefined)} bar - the bar value initialy passed and transformed, or nothing in case of error.
*/
next(null, bar);
}
and the following JSDoc command:
jsdoc --private callback-jsdoc-test.js
I generate the following files:
out/
--index.html
--global.html
--callback-jsdoc-test.js.html
-- <directories...>
and in global.html
there are a next foo~next What next after foo process ? line with a link on foo~next text which go to global.html#foo#~next but this link point on nothing...
2. Not use an inner path
So, I try to not use foo~next but just next.
/**
* The foo function for example.
* function foo
* @param {Object} bar - The baz parrameters.
* @param {next} next - What next after foo process ?
*/
function foo(bar, next) {
if (bar === "baz") {
return next(new Error("no baz allowed"));
}
bar += bar;
/**
* @callback next
* @param {(Object|null)} err - return error object in case of error, else null.
* @param {(Object|undefined)} bar - the bar value initialy passed and transformed, or nothing in case of error.
*/
next(null, bar);
}
After generation of doc with default template:
There is effectively a type def created as said in documentation and the global.html#next works as expected but this solution does not fit to my needs because if I used an other next variable as parameter of an other callback, two next variables will be enter in conflict. Also in this case next is global or this is not my intention because next is inner to foo. According to the documentation, I must use many nextOtherName name to referenced all possible next...
** 3. Declare explicitly that is an inner function**
I also try to add the @inner keyword explicitly with the @memberOf declaration as following:
/**
* The foo function for example.
* function foo
* @param {Object} bar - The baz parrameters.
* @param {foo~next} next - What next after foo process ?
*/
function foo(bar, next) {
if (bar === "baz") {
return next(new Error("no baz allowed"));
}
bar += bar;
/**
* @callback next
* @inner
* @memberOf foo~
* @param {(Object|null)} err - return error object in case of error, else null.
* @param {(Object|undefined)} bar - the bar value initialy passed and transformed, or nothing in case of error.
*/
next(null, bar);
}
After generation of doc with default template:
There is always a next type def as global type def (not what I want) with the next foo~next What next after foo process ? but link point on nothing...
** 4. Add a namespace **
If I use the first code with @memberOf and @namespace
/**
* The foo function for example.
* @namespace foo
* @param {Object} bar - The baz parrameters.
* @param {foo~next} next - What next after foo process ?
*/
function foo(bar, next) {
if (bar === "baz") {
return next(new Error("no baz allowed"));
}
bar += bar;
/**
* @callback next
* @memberOf foo~
* @param {(Object|null)} err - return error object in case of error, else null.
* @param {(Object|undefined)} bar - the bar value initialy passed and transformed, or nothing in case of error.
*/
next(null, bar);
}
After generation of doc with default template:
The global.htm is now foo.htm and type def is attached to foo.htm but because of @namespace, the function is now refferenced as a namespace and not as a function so the function description with the foo~next link does not appear... logical, and it's not what I want.
** 5. Use class in place of namespace **
If I use the previous code with @memberOf and @class
/**
* The foo function for example.
* @class foo
* @param {Object} bar - The baz parrameters.
* @param {foo~next} next - What next after foo process ?
*/
function foo(bar, next) {
if (bar === "baz") {
return next(new Error("no baz allowed"));
}
bar += bar;
/**
* @callback next
* @memberOf foo~
* @param {(Object|null)} err - return error object in case of error, else null.
* @param {(Object|undefined)} bar - the bar value initialy passed and transformed, or nothing in case of error.
*/
next(null, bar);
}
After generation of doc with default template:
There are effectively the function description AND a good link to callback type def but in this case I declare my simple function as a Class and it's absolutly not the case (no usage of new, not a constructor, etc.) so it's still not the good way.
** 6. Use the method keyword**
I decided after all this to use the @method keyword and it's the same issue that first example. Moreover, @method is useful for function into a @class, not global function...
So...
What is the correct way to comment a callback of simple function as a specific type def and not global?
