我尝试以多种方式使用@callback但我从未获得使用JSDoc API生成文档时使用的方式的文档。
1。我必须使用我期望的代码
使用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);
}
以及以下JSDoc命令：
jsdoc --private callback-jsdoc-test.js
我生成以下文件：
out/
--index.html
--global.html
--callback-jsdoc-test.js.html
-- <directories...>
并在global.html
有一条next foo~next What next after foo process ?行，foo~next文字上的链接指向global.html#foo#~next，但此链接指向任何内容......
2。不使用内部路径
因此，我尝试不使用foo~next，而只使用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);
}
使用默认模板生成doc后：
有效地创建了一个类型def，如文档中所述，global.html#next按预期工作，但此解决方案不符合我的需要，因为如果我使用其他next变量作为其他参数回调，两个next变量将在冲突中输入。同样在这种情况下next是global或者这不是我的意图，因为next是foo的内在。根据文档，我必须使用许多nextOtherName名称来引用所有可能的next ...
** 3.明确声明这是一个内部函数**
我还尝试使用@memberOf声明显式添加@inner关键字，如下所示：
/**
* 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);
}
使用默认模板生成doc后：
总是next类型def作为全局类型def（不是我想要的）next foo~next What next after foo process ?但链接点什么都没有...
** 4.添加命名空间**
如果我使用@memberOf和@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);
}
使用默认模板生成doc后：
global.htm现在是foo.htm，类型def附加到foo.htm但是由于@namespace，该函数现在被引用为命名空间而不是函数所以函数描述使用foo~next链接似乎不合逻辑，而且这不是我想要的。
** 5.使用class代替命名空间**
如果我使用前面的代码与@memberOf和@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);
}
使用默认模板生成doc后：
有效的函数描述和回调类型def的良好链接但在这种情况下我将我的简单函数声明为一个类，它绝对不是这种情况（不使用new，不是构造函数等）所以它是仍然不是好方法。
** 6.使用方法关键字**
毕竟我决定使用@method关键字，这与第一个例子的问题相同。而且，@ method可以用于函数到@class，而不是全局函数......
因此...
将简单函数的回调注释为特定类型def而非全局的正确方法是什么？