Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Hangs indefinitely #2438

Closed
claytonneal opened this issue Nov 2, 2023 · 5 comments
Closed

Hangs indefinitely #2438

claytonneal opened this issue Nov 2, 2023 · 5 comments
Labels
bug Functionality does not match expectation

Comments

@claytonneal
Copy link

claytonneal commented Nov 2, 2023

Search terms

typedoc hangs and no documentation produced

Expected Behavior

Documentation gets produced

Actual Behavior

No documentation produced

Steps to reproduce the bug

yarn typedoc --options typedoc.json --logLevel Verbose

The last line of the logs is:
[debug] Begin readme.md/package.json search at ./packages/core

after which nothing happens (left it running for > 4 hrs)

The repository is a mono repo, the config is:

typedoc.json

{
    "$schema": "https://typedoc.org/schema.json",
    "entryPoints": ["./packages/core/"],
    "entryPointStrategy": "packages",
    "out": "./api-docs",
    "readme": "none"
}

typedoc.base.json

{
    "$schema": "https://typedoc.org/schema.json",
    "compilerOptions":{
      "strictNullChecks": false
    },
    "skipErrorChecking": true,
    "excludeExternals": true,
    "exclude": [ "**/*+(index|.spec|.e2e|test).ts" ],
    "externalPattern": [
      "**/node_modules/**"
    ],
    "readme": "none",
    "excludeReferences": true
}

and the config file inside the package:

{
    "extends": ["../../typedoc.base.json"],
    "entryPoints": ["src/core.ts"]
  }

Environment

  • Typedoc version: 0.25.3
  • TypeScript version: 5.2.2
  • Node.js version: 18.12.1
  • OS: macos
@claytonneal claytonneal added the bug Functionality does not match expectation label Nov 2, 2023
@claytonneal
Copy link
Author

Full logs:

[debug] Reading tsconfig at ./tsconfig.json
[debug] Using TypeScript 5.2.2 from ./node_modules/typescript/lib
[debug] Expanded ./packages/core to:
        ./packages/core/package.json
[debug] Reading project at ./packages/core
[debug] Reading tsconfig at ./packages/core/tsconfig.json
[info] Converting project at ./packages/core
[debug] Using TypeScript 5.2.2 from ./node_modules/typescript/lib
[debug] Expanded ./packages/core/src/core.ts to:
        ./packages/core/src/core.ts
[debug] Converting with 1 programs 1 entry points
[debug] Finished getting entry points in 423ms
[debug] Begin readme.md/package.json search at ./packages/core

@Gerrit0
Copy link
Collaborator

Gerrit0 commented Nov 3, 2023

Can't do anything for this without a reproduction

@Gerrit0 Gerrit0 added the needs reproduction Needs a minimal reproducible case label Nov 3, 2023
@claytonneal
Copy link
Author

I found the issue, the export interface caused the hang
removing that export fixes the issue

export interface Certificate {
    purpose: string;
    payload: {
        type: string;
        content: string;
    };
    domain: string;
    timestamp: number;
    signer: string;
    signature?: string;
}

export type { Certificate };

@claytonneal
Copy link
Author

i know have a different scenario that im investigating where its hanging indefinetly
it would be good to output logs when this happens and abort after a certain time
hanging indefinetly makes me nervous about having this in CICD

@Gerrit0
Copy link
Collaborator

Gerrit0 commented Nov 3, 2023

Declaration files are the root of all evil. TypeDoc got stuck because I made the assumption that if a symbol has ts.SymbolFlags.Alias, and I ask TS for what the alias is pointing to, eventually I'll get to the end of a chain.

In normal TS code this is totally fine. (.ts is where all your code ought to be anyways! Declaration files should only be written to describe external JS)

In declaration files, this is also an error, unless the worst compiler option, skipLibCheck is turned on, which tells TS to not check code in declaration files for type errors in many cases, including this one. Detecting and fixing this specific issue isn't difficult, but in general, if code has type errors, TypeDoc's behavior is not guaranteed.

Aborting after some time is something that can't be reasonably implemented in TypeDoc without re-implementing every loop anywhere to introduce a yield, which is not something I'm going to do. Your CI system is already equipped to deal with this, there is a timeout-minute property for GitHub actions, and other CI systems have similar options.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Functionality does not match expectation
Projects
None yet
Development

No branches or pull requests

2 participants