Clarification of how to properly include typedefs in documentation built for an ES module.

Search terms

typedef, esmodule, class, “referenced but not included in the documentation”

Question

I am using typedoc to document an ESModule. An example file in that module defines a class and its constructor parameter(s) as follows (this is a simplified example):

File 1: Class Declaration - some-class.mjs

/**
 * @typedef {Object} SomeDataStructure
 * @property {string} foo      A string
 * @property {number} bar   A number
 */

/**
 * A class that does a thing
 */
export default class SomeClass {
  /**
   * Construct an instance of SomeClass using provided data
   * @param {SomeDataStructure} data   Input data
   */
  constructor(data) {
    this.data = data;
  }
}

The documentation is built by targeting another file which is the entry-point that aggregates exports for different components of the module:

File 2: Module Entrypoint - module.mjs

export {default as SomeClass} from "./some-class.mjs"

What Goes Wrong?

When trying to build documentation for the module the following warning is displayed:

Warning: SomeDataStructure, defined at common/some-class.mjs:2, is referenced by foundry.SomeClass.data but not included in the documentation.

Documentation is built for SomeClass, but the data type of its constructor parameter is not documented nor is the SomeDataStructure typedef available for inspection in the resulting documentation.

I realize this is a somewhat uncommon use case since the source of the module is not TypeScript but rather an ESModule directly, but this use case is portrayed as being supported by https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#typedef-callback-and-param.

Is this a typedoc bug? Is this a problem with the way I have structured the module code? Thanks for your guidance.

[aaclayton]

Is the purpose of API documentation not to inform the user how to use the exported classes and functions of a module? What use is API documentation if the docs don’t tell you how to construct SomeClass in my example? Is this not a failure of the documentation that it provides no instruction here?

It feels like your perspective loses sight of the fundamental purpose for documentation in favor of turning a (surmountable) technical limitation into a philosophical line in the sand that ultimately doesn’t serve the end user.

I hope my feedback on this area is useful to you and that your perspective may shift over time, but either way thank you for your time spent looking into this matter and for your development of this codebase.

[aaclayton]

I think it would be a shame for the discussion in this thread to be treated as “closed” even though the original question was answered. I really believe this represents a shortcoming in the current functionality of documentation generators and it would be great to keep this issue open to reflect the possibility to improve the software, even if those improvements are not prioritized in the short term.