Typedoc: --includeDeclarations causes typedoc to hang indefinitely

[balupton]

Affecting eachr#dev-typescript-dts

Reproduce with:

git clone [email protected]:bevry/eachr.git
cd eachr
git checkout dev-typescript-dts
npm install
npm run our:meta:docs:typedoc

Hangs with:

> [email protected] our:meta:docs:typedoc /Users/balupton/Projects/active/eachr
> typedoc --includeDeclarations --mode file --exclude '**/*test*' --name "$npm_package_name" --readme ./README.md --out ./docs ./source


Using TypeScript 3.1.6 from /Users/balupton/Projects/active/eachr/node_modules/typedoc/node_modules/typescript/lib

And the version details:

> uname -a
Darwin balbook-2018.local 18.2.0 Darwin Kernel Version 18.2.0: Mon Nov 12 20:24:46 PST 2018; root:xnu-4903.231.4~2/RELEASE_X86_64 x86_64

> typedoc --version

TypeDoc 0.13.0
Using TypeScript 3.1.6 from /usr/local/lib/node_modules/typedoc/node_modules/typescript/lib

[aciccarello]

I was able to run locally in ~190 seconds on a relatively fast computer which is not great but it did complete. I would recommend excluding the node modules directory to avoid unnecessary documentation as that appears to be the main cause of the slowdown. Using the option --exclude '**/+(*test*|node_modules)/**' in combination with the changes from #896 brought the build down to under 5 seconds.

[aciccarello]

_Response from @9oelM merged from #919:_

The problem

Yes I have looked at #913 and the comment by @aciccarello also. But I still find that --includeDeclarations option would make typedoc hang like forever without any warnings if there are no d.ts declaration files.

Context

I was planning to add d.ts files later on but I did not want to edit typedoc config later too, so I just added includeDeclarations option to the config (typedoc.js). But the problem was typedoc would hang somewhere in its process, probably looking for .d.ts files.

I tested this problem each time with the option specified on cli (by specifying --includeDeclarations) and in typedoc.js in rootdir.

Reproducing the problem

You can test directly from c9.io here:
(on c9 cli)

typedoc --out docs test.ts

or git clone this repo to test it out:

git clone https://github.com/9oelM/typedoc-test.git
cd typedoc-test
npm install
typedoc --out docs test.ts

this is going to show something like

Using TypeScript 3.1.6 from /home/ubuntu/workspace/node_modules/typedoc/node_modules/typescript/lib

and hang forever.

This is the content of the config file used:
typedoc.js

module.exports = {
  module: "commonjs",
  mode: "modules",
  target: "es5",
  out: "docs/",
  name: "justTesting",
  exclude: ["node_modules/**", "**/"],
  includeDeclarations: true,
}

I waited for several minutes but it won't work. It is even clearer that includeDeclarations option is the problem when you test it out without it (just exclude the last line from the above config):

$ typedoc --out docs test.ts 

Using TypeScript 3.1.6 from /home/ubuntu/workspace/node_modules/typedoc/node_modules/typescript/lib
Rendering [========================================] 100%

Documentation generated at /home/ubuntu/workspace/docs

It would work without includeDeclarations specified.

So..

I just hope there would be some kind of safety measures in case users put includeDeclarations option in advance of creating d.ts files, or by any other ignorance because it is typedoc is going to hang forever and not going to tell you the problem!

[aciccarello]

@9oelM What makes you think that TypeDoc isn't hanging on type definition files in node_modules?

[9oelM]

@aciccarello woops. did not realize there is a problem in the exclude option, especially when excluding node_modules, as suggested by many other issues. Hope the #896 is going to be merged soon...

[Gerrit0]

With the v0.14.0 release, this has been resolved thanks to #890 and #896