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

Question

我给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 也不需要尾随代码，因此它肯定可以以某种方式在没有代码的情况下添加注释。但为什么它在我的情况下不起作用？

Answer 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 就不需要自己弄清楚了。

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

Why does jsDoc not parse my comment that has no trailing code?

jsdoc

jsdoc3