Saturday, 4 December 2021

JSDOC with import/export syntax (ES modules)

How does one specify exported (public) properties of a module with JSDoc when using import and export?

My module structure is

/lib
 |- src/
 |  |- func-a.js
 |  |- func-b.js
 |- index.js   

lib/src/func-a.js

/** Module for queue A
 * @exports funcA/funcA
 */

/**
 * Processes A queue
 * @public
 * @param {number} n - input number
 * @returns {number} result - output number
 */
const funcA = (n) => {
  return addTwoToN(n)
}

/**
 * Adds integer two to input
 * @private
 * @param {number} n - input number
 * @returns {number} addition - input plus two
 */
const addTwoToN = (n) => n + 2

export default funcA

lib/src/func-b.js

/**
 * Processes B queue
 * @public
 * @param {number} n - input number
 * @returns {number} result - output number
 */
const funcB = (n) => {
  return subtractTwoFromN(n)
}

/**
 * @private
 * @param {number} n - input number
 * @returns {number} subtraction - input minus two
 */
const subtractTwoFromN = (n) => n - 2

export default funcB

And finally lib/index.js

import funcA from './src/func-a';
import funcB from './src/func-b';

/**
 * Func module
 * @module func
 */
export {
  /**
   * Queue func A
   * @module func/funcA
  */
  funcA,
  /**
    * Queue func B
    * @module func/funcB
  */
  funcB,
}

Now if I create some other Javascript file and do import { funcA, funcB } from 'lib/, it seems to pick up annotation in the editor and I'm getting intellisense which is nice. Where I'm stuck is when trying to generate documentation via jsdoc CLI like so:

jsdoc lib/index.js --destination docs/

I end up with this:

JSDOC documentation

Which is incomplete, there's no funcB mentioned. When opening funcA link in sidebar, I only get this:

JSDOC detail documentation

There is no API documentation for that part of the library.

I am probably approaching this in a wrong way. Can I even use multiple @module annotations? Or should I be using @typedef instead? I expected the documentation to basically show structure of the lib/ and display the annotation for items marked with @public but maybe my expectation is totally different.



from JSDOC with import/export syntax (ES modules)

No comments:

Post a Comment