scottohara
commented
4 years ago By default, JSDoc only looks for *.js files. When running npm run docs, the error There are no input files to process. is thrown.
Tried setting includePattern: ".+\\.(t|j)s$", in jsdoc.json to get it to recognise *.ts files, but that reports numerous errors, e.g.
ERROR: Unable to parse /Users/scotto/GitHub/tvmanager/src/components/index.d.ts: This experimental syntax requires enabling one of the following parser plugin(s): 'flow, typescript' (10:7)
ERROR: Unable to parse /Users/scotto/GitHub/tvmanager/src/components/list.ts: Unexpected token (39:9)
ERROR: Unable to parse /Users/scotto/GitHub/tvmanager/src/components/progressbar.ts: Unexpected token (25:9)
ERROR: Unable to parse /Users/scotto/GitHub/tvmanager/src/components/toucheventproxy.ts: Unexpected token (22:8)It looks like we may need to use something like jsdoc-plugin-typescript if we wish to continue using JSDoc.
With the switch to Typescript, arguably the value of JSDoc comments has reduced slightly. (parameter/return types are now explicit in the function signature itself, and therefore the risk of forgetting to update the comment when the function sig changes is removed).
There is potentially still value in documenting parameter descriptions or usage, however; as well as being able to generate external, standalone API docs.
During the TS conversion, we purposely didn't update JSDoc comments (because we weren't sure if the effort would be wasted, if we later removed them entirely); so it is possible/likely that some comments no longer accurately reflect reality.
Need to decide if we:
(see also: older discussion of issues with JSDoc3 https://github.com/scottohara/tvmanager/issues/34)