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

Question

I added a new plugin to jsdoc, introducing a new tag:

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

But jsDoc seems to only create a new doclet when the comment is followed by some javascript code. This works:

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

But this does not get recognized:

/**
 * @newtag name
 */

The native jsDoc tag @module does not require trailing code either so it should definately somehow be possible to add comments without code. But why does it not work in my case?

Rob Raisch · Accepted Answer · 2021-09-30T18:50:15.340

JsDoc allows you to document arbitrary things without trailing code if you provide everything it needs to do so. For instance, here is a module file named 'foo.js' with no code that documents a member:

/**
 * @module Foo
 */

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

which will produce the following result (assuming a very simple output template):

Foo

Members

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

A named member of Foo.

By default, when JsDoc parses your source code, it connects a JsDoc comment (internally referred to as a 'doclet') with the feature following it in your source code.

If you do not provide a name in the doclet, JsDoc uses the source to discover a value for the @name tag, as in:

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

To create a doclet without attaching it to any trailing code, you simply need to assign a name so JsDoc doesn't need to figure it out for itself.

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

1 Answers1