search

angular / dgeni-packages

A collection of dgeni packages for generating documentation from source code.
MIT License
142 stars 106 forks source link

fix(jsdoc): runtime error when jsdoc uses unknown tag definition #323

Closed devversion closed 2 years ago

devversion commented 2 years ago

Dgeni packages JSDoc does not support @throws by default (surprisingly as a side note). Now if a project like Angular Material uses that somewhere, the Tag will be instantiated without a tagDef because there is none.

Later after parsing (when the Tag was created), the extract tags processor will log an error for such tags. This logic does not work as expected currently because such Tag instances do not necessarily have the errors field, resulting in runtime exceptions like:

TypeError: Error running processor "extractTagsProcessor":
Cannot read properties of undefined (reading 'forEach')
    at /private/var/tmp/_bazel_paul/24d3819ba30ba6e17ef227c181228208/sandbox/darwin-sandbox/4/execroot/angular_material/bazel-out/host/bin/tools/dgeni/dgeni.sh.runfiles/npm/node_modules/dgeni-packages/jsdoc/processors/extract-tags.js:198:21
    at Array.forEach (<anonymous>)
    at formatBadTagErrorMessage (/private/var/tmp/_bazel_paul/24d3819ba30ba6e17ef227c181228208/sandbox/darwin-sandbox/4/execroot/angular_material/bazel-out/host/bin/tools/dgeni/dgeni.sh.runfiles/npm/node_modules/dgeni-packages/jsdoc/processors/extract-tags.js:188:22)
    at tagExtractor (/private/var/tmp/_bazel_paul/24d3819ba30ba6e17ef227c181228208/sandbox/darwin-sandbox/4/execroot/angular_material/bazel-out/host/bin/tools/dgeni/dgeni.sh.runfiles/npm/node_modules/dgeni-packages/jsdoc/processors/extract-tags.js:92:18)

This commit fixes that runtime error. It seems like this error has been introduced as a side-effect of switching away from Lodash to actual tag.errors.forEach.

Interestingly before this change, tags like @throws were just processed as is silently and no warning/error was printed at all.

devversion commented 2 years ago

cc. @petebacondarwin. Not sure if you still would like to be kept in the loop on this/want to review.