Code gets read but is not generated at all... about jsdoc-md HOT 1 CLOSED

The readme explains how to write compatible JSDoc comments. See:

Missing JSDoc tags are not inferred by inspecting the code, so be sure to use all the necessary tags.

— https://github.com/jaydenseric/jsdoc-md/tree/v11.0.2#no-code-inference

Over the years I noticed that one of the biggest frustrations with using tools that generate API docs from source JSDoc is that they often have bugs about reading the code the JSDoc comment is associated with to infer particular details about the member being documented (especially the kind and name). They have bugs because they make a complicated mess of parsing the code, traversing the AST, etc. Also, when new ES syntax is added to the language these tools always took a very long time to update to understand it and not crash horribly or miss information.

It is a goal of jsdoc-md is to purely look at the JSDoc comments to generate the API docs, so it's very reliable and predictable. At a minimum, each JSDoc comment (that you want to appear in the generated API docs) should have these tags:

• @kind
• @name

For a few kinds, there are shorthand tags that combine the kind and name into one tag:

• @typedef
• @callback

This is useful for when you need to support tools like TypeScript that don't understand the separated name and kind tags.

You can then use additional supported tags to flesh out the details relevant to the kind:

https://github.com/jaydenseric/jsdoc-md/tree/v11.0.2#tag-subset

Unsupported tags not in that list are still safe to use for other tooling, they just get ignored by jsdoc-md.

Here are the necessary changes to make to achieve compatibility:

  /**
+  * @kind constant
+  * @name test
   * @type {Number}
   */
  const test = 0

  /**
+  * @kind function
+  * @name test2
   * @param {Number} lol - oh no...
   * 
   * @returns {0}
   */
  function test2(lol) { return 0 }

I'm currently in the process of migrating from Node.js to Deno, which has an evolving built-in system for scanning code and JSDoc to generate API docs. I'm waiting for it to stabilize a bit before I figure out if it can be used on it's own in my future Deno related or even Node.js related projects or if it can be used as part of a new Deno alternative to jsdoc-md. One of the things that will probably change in my future tooling is I will align to the Deno flavor of TypeScript JSDoc and might leverage code inference, since the smarts to do so will be part of the platform and much more reliable.

from jsdoc-md.