标签: jsdoc

我花了很长时间在互联网上寻找使用jsdoc正确记录回调的最佳方法,但遗憾的是,我还没有找到一个好的.

这是我的问题:

我正在为开发人员编写Node.js库.该库提供了开发人员将使用的多个类,函数和方法.

为了使我的代码清晰易懂,以及(希望)将来自动生成一些API文档,我已经开始在我的代码中使用jsdoc来自我记录正在发生的事情.

假设我定义了如下函数:

function addStuff(x, y, callback) {
  callback(x+y);
});

使用jsdoc,我目前正在记录此函数,如下所示:

/**
  * Add two numbers together, then pass the results to a callback function.
  *
  * @function addStuff
  * @param {int} x - An integer.
  * @param {int} y - An integer.
  * @param {function} callback - A callback to run whose signature is (sum), where
  *  sum is an integer.
  */
function addStuff(x, y, callback) {
  callback(x+y);
});

我觉得上面的解决方案有点像hack-ish,因为我无法用绝对术语来指定回调函数应该接受什么.

理想情况下,我想做的事情如下:

/**
  * Add two …

有下一个例子:

var CONF = {
    locale: {
        "en": {
            name: "English",
            lang: "en-US"
        },
        "es": {
            name: "Spanish",
            lang: "es-ES"
        }
    }
};

并且知道locale属性包含的是来自数据库的字典对象,如何使用JSDoc记录其内部属性？

目前我正在考虑typedef 为我的语言环境对象输入,那么我可以将该locale属性设置为我定义的类型的数组吗？这是正确的方法吗？

以前我总是记录我的对象参数如下:

/**
 * Description of the function
 *
 * @param {Object} config - The configuration
 * @param {String} config.foo
 * @param {Boolean} [config.bar] - Optional value
 * @return {String}
 */
function doSomething (config = {}) {
  const { foo, bar } = config;
  console.log(foo, bar);
  // do something
}

但我不确定desctructured函数参数的最佳方法是什么.我是否只是忽略了对象,以某种方式定义它或者记录它的最佳方式是什么？

/**
 * Description of the function
 *
 * @param {String} foo
 * @param {Boolean} [bar] - Optional value
 * @return {String}
 */
function doSomething ({ foo, bar } = {}) …

我有一些用CoffeeScript编写的代码,我想用Google Closure Compiler优化生成的JavaScript,所以这些文件需要用JSDoc记录.

我的问题是,如何记录*.coffee文件以生成包含用于闭包编译器的工作JSDoc的javascript？

还有一个问题:有没有办法在*.coffee中保留单行注释？

我正在尝试记录Express中间件,但WebStorm中的内置验证工具告诉我在以下JSDoc块中错误地分配了类型:

/**
 * My middleware.
 *
 * @param {Object} req
 * @param {Object} res
 * @param {Function} next
 * @return {Object}
 */
exports.show = function(req, res, next) {
    ...
};

在Express消息来源中,我没有找到任何@typedef帮助我.另外,我想避免像这样的事情@param {*}.

使用JSDoc记录Express中间件的正确方法是什么？谢谢你的帮助.

你知道<code />JSDoc中是否有某种标签吗？我需要在我的文档中添加代码片段,如下所示:

/**
 * This function does something see example below:
 *
 * var x = foo("test"); //it will show "test" message
 *
 * @param {string} str: string argument that will be shown in message
 */
function foo(str)
{
   alert(str);
}

我需要将注释中的代码作为代码显示在JSDoc中(如果没有突出显示语法,至少像预先格式化或具有灰色背景的东西).

是否存在jsdoc的param标签的有效类型的列表？例如,

@param {type} myParam Some parameter description

我知道类似number和String有效的东西,但如果我想记录数字是整数怎么办.是否int有效？

我做了一些谷歌搜索,但我似乎无法找到一个完整的列表.

我一直在尝试使用JSDoc3来生成文件的文档,但是我遇到了一些困难.该文件(Require.js模块)基本上如下所示:

define([], function() {

    /*
     * @exports mystuff/foo
     */
    var foo = {
        /**
         * @member
         */
        bar: {
            /**
             * @method
             */
            baz: function() { /*...*/ }
        }
    };

    return foo;
}

问题是,我无法baz在生成的文档中显示出来.相反,我只获得一个foo/foo模块的文档文件,该文件列出了一个bar成员,但bar没有baz(只是一个foo源代码的链接).

我已经尝试改变bar指令了@property,我已经尝试将baz指令更改为@member或@property,但这些都没有帮助.无论我做什么,巴兹似乎都不想表现出来.

有谁知道我可以用什么指令结构让baz出现在生成的文档中？

PS我试过在JSDoc网站http://usejsdoc.org/howto-commonjs-modules.html上阅读这样的页面,但它只描述了案例foo.bar,而不是foo.bar.baz.

我正在使用jQuery的$.widget()基类"类",它提供了一种option()方法.由于该方法不在我的代码中,因此我无法记录参数.

我试图将jsDoc放在默认选项文字中的字段上,但它们根本就没有被选中.然后我尝试在同一个对象文字上使用@class和@lends标签,但这可能会让人很困惑,因为对象文字实际上并不是一个类.

我尝试过的另一种方法是@param options.field description在构造函数的jsDoc中添加类似的东西.但是,这样做的缺点是将文档与代码分开.此外,构造函数实际上没有调用的参数,options因为它全部由jQuery处理.

你是如何Javascript专家处理这个？是否应该提出新标签？

我目前正在开发一个NodeJS项目,并发现没有内置的功能来为函数/方法创建JSDoc注释.

我知道存在的TypeScript定义,但我找不到任何符合我需要的东西.

例如,WebStorm具有一些非常简洁的JSDoc功能.可以以某种方式实现类似的功能吗？