为啥 jsDoc 不解析我没有尾随代码的评论？

Posted 2023-03-15

【中文标题】为啥 jsDoc 不解析我没有尾随代码的评论？

【英文标题】：Why does jsDoc not parse my comment that has no trailing code?为什么 jsDoc 不解析我没有尾随代码的评论？

【发布时间】：2016-09-27 10:52:02

【问题描述】：

我在jsdoc中添加了一个新插件，引入了一个新标签：

dictionary.defineTag("newtag", 
  mustHaveValue: false,
  canHaveType: false,
  canHaveName: true,
  onTagged: function(doclet, tag) 
    doclet.newtag = tag.value;
    doclet.kind = "newitem";
  
);

但 jsDoc 似乎只在注释后跟一些 javascript 代码时创建一个新的 doclet。这有效：

/**
 * @newtag name
 */
somename = function();

但这并没有得到认可：

/**
 * @newtag name
 */

本机 jsDoc 标签 @module 也不需要尾随代码，因此它肯定可以在没有代码的情况下添加 cmets。但为什么它在我的情况下不起作用？

【参考方案1】：

如果您提供所需的一切，JsDoc 允许您记录任意内容而无需尾随代码。例如，这是一个名为“foo.js”的模块文件，没有记录成员的代码：

/**
 * @module Foo
 */

/**
 * A named member of Foo.
 *
 * @name Bar
 * @type String 
 * @memberof Foo
 */

这将产生以下结果（假设一个非常简单的输出模板）：

Foo

Members

(static) Bar :String
| Source: foo.js, line 5

A named member of Foo.

默认情况下，当 JsDoc 解析您的源代码时，它会将 JsDoc 注释（内部称为“doclet”）与源代码中它后面的功能连接起来。

如果您没有在 doclet 中提供名称，JsDoc 将使用源来发现 @name 标记的值，如下所示：

/**
 * A useless string constant.
 * @type String
 */
const Bar = 'useless';

要创建一个 doclet 而不将其附加到任何尾随代码，您只需指定一个名称，这样 JsDoc 就不需要自己找出它。