Feature request: Support jsdoc style typescript comments in js files

[bendtherules]

Typescript supports a way to add jsdoc-style comments (that indicate type information) within js files (https://github.com/Microsoft/TypeScript/wiki/JSDoc-support-in-JavaScript). This is quite a valid way to use Typescript without moving to ts files.

But these files don't seem to get picked up or processed by typedoc to generate relevant documentation. Is it possible to support this?
(TS compiler api should already have ways to understand this comments, the way VSCode does)

[aciccarello]

@bendtherules TypeDoc should already support this? Are you passing the allowJS compiler option? If so, please let us know how we can reproduce your issue. Thanks!

[jcardenas9x]

I tried to use @type {function(): string} to describe a function signature in JavaScript. I plan to use typedoc-plugin-markdown which works well in general but the generated Markdown improperly parses the JSDoc into the following:

*__type__*: {function(): string}

Which is a bit odd considering this is supported normally in TypeScript. I do wish I had the luxury of time to explore precisely what kind of annotations and code is allowed in TypeDoc to properly group and document stuff but it's a bit tight for me at the moment.

For reference, using the default TypeDoc theme results in this:

[bendtherules]

Repro repo: https://github.com/bendtherules/repro-typedoc-issue-jsdoc/tree/without-ext-types

Trying to run: npx typedoc --tsconfig ./tsconfig.json --out ./docs ./src/

But it doesn't have any methods of Calculations in the output.
In master branch, the .js files import stuff from other .ts files - types in .ts do show up in output (but not from js files).

It might be just something wrong with the require/module.exports syntax here or a wrong tsconfig.json, but I can't really figure out.

[bendtherules]

Hi, just checking back.

Is this problem reproducible on someone else's end?
If this doesn't work, is there any simplified example which is known to work?

[aciccarello]

I was able to get it to work with some slight modifications.

I changed the input file to explicitly be the js file. The TS compiler was complaining about overriding the file so I added an outDir to the tsconfig.json. With this configuration TypeDoc was able to generate the Calculations docs.

npx typedoc --tsconfig ./tsconfig.json --out ./docs ./src/index.js

[bendtherules]

Thanks, this works. Forgot to test it out earlier.

Should I keep it open as it should automatically pick that up? Or is it outside typedocs's scope (and something that typescript should do itself) ?

[Gerrit0]

Providing just the input directory should work, and should include all files inside of that directory, so if including ./src/ doesn't work (does src? ./src?), we definitely need an issue to track that, though it's not the focus of this issue so a new one should probably be opened.

If the outDir setting was the issue, and not the input directory for typedoc, then this would be a configuration, not a typedoc issue.

[bendtherules]

outDir is not the solution, just something needed to make TS not throw an error. It is not used for any actual output.

None of the variations of providing folder name like ./src/ works. (It creates empty index, doesn't catch inner files).

[bendtherules]

Ideally though, files should be automatically picked up using include/exclude provided in tsconfig.json.

Providing it in CLI shouldn't be required for js, as it's not required for ts.

[Gerrit0]

Well, it was fairly easy to track down why js files weren't included when specifying a directory - expandInputFiles doesn't check for the .js extension.

This will fix your original command, but I'm not sure if the input files will be picked up automatically as ts files apparently are (never realized this...)