webdoc-labs / webdoc

Documentation generator for the web
https://www.webdoclabs.com
Other
79 stars 9 forks source link

Crash occurred when documenting interfaces as typedefs #76

Closed bigtimebuddy closed 3 years ago

bigtimebuddy commented 3 years ago

Was having a difficult time documenting interface types as typedef. Here's the example:

/**
 * @memberof PIXI
 * @typedef {object}
 * @property {function} init - Called when Application is constructed, scoped to Application instance.
 *  Passes in `options` as the only argument, which are Application constructor options.
 * @property {function} destroy - Called when destroying Application, scoped to Application instance
 */
export interface IApplicationPlugin {
    init: (...params: any[]) => any;
    destroy: (...params: any[]) => any;
}

This produces a crash when trying to build:

(node:11151) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'steps' of undefined
    at query ([...]/pixi.js/node_modules/@webdoc/model/lib/query/query.js:17:13)
    at LinkerPluginImpl.linkTo ([...]/pixi.js/node_modules/@webdoc/template-library/lib/template-plugins/LinkerPlugin.js:156:23)
    at eval (lodash.templateSources[0]:101:16)
    at Array.forEach (<anonymous>)
    at eval (lodash.templateSources[0]:98:14)
    at Array.forEach (<anonymous>)
    at TemplateRenderer.eval (lodash.templateSources[0]:13:10)
    at TemplateRenderer.partial ([...]/pixi.js/node_modules/@webdoc/template-library/lib/TemplateRenderer.js:128:38)
    at TemplateRenderer.render ([...]/pixi.js/node_modules/@webdoc/template-library/lib/TemplateRenderer.js:140:24)
    at TemplatePipeline.render ([...]/pixi.js/node_modules/@webdoc/template-library/lib/TemplatePipeline.js:23:32)

Workaround

Putting the typedef after the interface and adding the name to typedef didn't break building.

export interface IApplicationPlugin {
    init: (...params: any[]) => any;
    destroy: (...params: any[]) => any;
}

/**
 * @memberof PIXI
 * @typedef {object} IApplicationPlugin
 * @property {function} init - Called when Application is constructed, scoped to Application instance.
 *  Passes in `options` as the only argument, which are Application constructor options.
 * @property {function} destroy - Called when destroying Application, scoped to Application instance
 */
ShukantPal commented 3 years ago

I looked into this issue. The crash isn't related to the @typedef at all. Looks like webdoc wasn't parsing interface extends properly:

interface IArrayBuffer extends ArrayBuffer {}

This was being parsed into:

{
  ...,
  name: "IArrayBuffer", 
  extends: [""],
}

From there, some weird stuff happened when trying to find that interface.

ShukantPal commented 3 years ago

I know it sounds totally unrelated but that's where the error was coming from. Adding the snippet in isolation worked fine.

ShukantPal commented 3 years ago

This is released in webdoc 1.1.5