Typedoc: JSDoc @typedef yields ERR_ASSERTION in convertTypeAlias

[rreusser]

Search terms

ERR_ASSERTION, @typedef, jsdoc

Expected Behavior

Expected to compile a minimal example using a JSDoc @typedef statement.

Actual Behavior

Fails an assertion in convertTypeAlias.

Assertion failure output...

npm run build:docs                                                                                                                    <<<

> typedoc-repro@ build:docs /path/to/tsdoctest
> typedoc

Debug: Arguments reader reading with: []
Debug: Arguments reader reading with: []
Debug: Using TypeScript 4.1.3 from /path/to/tsdoctest/node_modules/typescript/lib
Debug: Converting with 1 programs
Debug: Begin readme search at /path/to/tsdoctest/src
TypeDoc exiting with unexpected error:
{ AssertionError [ERR_ASSERTION]: The expression evaluated to a falsy value:

  assert(declaration)

    at Object.convertTypeAlias (/path/to/tsdoctest/node_modules/typedoc/dist/lib/converter/symbols.js:103:5)
    at Object.convertSymbol (/path/to/tsdoctest/node_modules/typedoc/dist/lib/converter/symbols.js:75:79)
    at Converter.convertExports (/path/to/tsdoctest/node_modules/typedoc/dist/lib/converter/converter.js:167:23)
    at Converter.compile (/path/to/tsdoctest/node_modules/typedoc/dist/lib/converter/converter.js:143:34)
    at Converter.convert (/path/to/tsdoctest/node_modules/typedoc/dist/lib/converter/converter.js:42:14)
    at Application.convert (/path/to/tsdoctest/node_modules/typedoc/dist/lib/application.js:151:31)
    at run (/path/to/tsdoctest/node_modules/typedoc/bin/typedoc:59:25)
    at Object. (/path/to/tsdoctest/node_modules/typedoc/bin/typedoc:26:1)
    at Module._compile (internal/modules/cjs/loader.js:778:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
  generatedMessage: true,
  name: 'AssertionError [ERR_ASSERTION]',
  code: 'ERR_ASSERTION',
  actual: undefined,
  expected: true,
  operator: '==' }

Steps to reproduce the bug

See minimal repro here: https://github.com/rreusser/typedoc-repro

A single JSDoc statement copied verbatim from this example is sufficient to cause the error:

/** @typedef {Object} SpecialType - creates a new type named 'SpecialType' */

I'm new to TypeScript, so please forgive any obvious errors, but it seems like this is minimal enough that I believe it should be valid usage. tsc runs and produces the expected output. It looks like this project is moving quickly at the moment (thanks soo much for your effort! This is a great project! ❤️), so it seemed to meet the threshold of reporting.

Environment

• Typedoc version: v0.20.5
• TypeScript version: 4.1.3
• Node.js version: 15.5.0
• OS: Mac OS X 10.13.6

[Gerrit0]

This is unfortunately expected right now, we need special casing for JSDoc type nodes because the compiler doesn't convert them into normal type nodes - #1214.

There is a workaround - set "declaration": true in your tsconfig, compile, then point TypeDoc at the emitted declaration files instead of the JS

[rreusser]

Thanks for the prompt answer! Hmm… I've tried that but I get Unable to locate entry point on a .d.ts file.

$ ls dist
sample.d.ts sample.js



$ cat dist/sample.d.ts
/**
 * - creates a new type named 'SpecialType'
 */
type SpecialType = Object;



./node_modules/.bin/typedoc --entryPoints dist/sample.d.ts                                                                                  <<<
Debug: Using TypeScript 4.1.3 from /path/to/tsdoctest/node_modules/typescript/lib
Debug: Converting with 1 programs
Debug: Begin readme search at /path/to/tsdoctest/dist
Warning: Unable to locate entry point: /path/to/tsdoctest/dist/sample.d.ts
Rendering [========================================] 100%
Info: Documentation generated at /path/to/tsdoctest/docs

(I've updated it to actually export a function which uses the defined type but still get the same error. I've also tried removing tsconfig.json to ensure this happens with the plain command and that none of the tsconfig is interfering.)

[Gerrit0]

So... I started debugging that, then decided to take a second look at how difficult supporting @typedef was. Turns out, not nearly as difficult as I thought! 0.20.6 includes support for it.

[rreusser]

Wow! I appreciate that so much! I was considering switching to pure TS instead of JSDoc style, but I'll give this another shot. I'm glad to keep poking at this, file issues, and get involved in more substantial debugging, but I also totally respect if that would be pushing what it supports in a direction that you're not that interested in investing. I'll give it a shot, but please don't hesitate to or feel bad about responding that it's just not particularly interesting to you if that's the case. Thanks again and happy new year! 🎉