如何从“.d.ts”文件生成 TypeScript API 文档？

如何从 .d.ts 文件生成typescript API文档？

我尝试 typedoc 传输 这个库 ：

% npx typedoc index.js 
[warning] The entry point ./index.js is not referenced by the 'files' or 'include' option in your tsconfig
[error] Unable to find any entry points. See previous warnings
[error] Found 1 errors and 1 warnings

并且也不能直接从 .d.ts 文件传输：

% npx typedoc tree-sitter.d.ts 
tree-sitter.d.ts:187:51 - error TS2580: Cannot find name 'Buffer'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node`.

187       constructor(language: any, source: string | Buffer);
                                                      ~~~~~~

tree-sitter.d.ts:206:7 - error TS1165: A computed property name in an ambient context must refer to an expression whose type is a literal type or a 'unique symbol' type.

206       [Symbol.iterator](): Iterator<string>;
          ~~~~~~~~~~~~~~~~~

tree-sitter.d.ts:206:8 - error TS2585: 'Symbol' only refers to a type, but is being used as a value here. Do you need to change your target library? Try changing the 'lib' compiler option to es2015 or later.

206       [Symbol.iterator](): Iterator<string>;
           ~~~~~~

tree-sitter.d.ts:206:28 - error TS2583: Cannot find name 'Iterator'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2015' or later.

206       [Symbol.iterator](): Iterator<string>;
                               ~~~~~~~~

[error] Found 4 errors and 0 warnings

You're getting those errors because Typedoc needs a JavaScript/TypeScript context to understand the types in your .d.ts file. Here's how to generate documentation from .d.ts files using Typedoc:

1. Create a minimal TypeScript configuration file ( tsconfig.json ):

{
  "compilerOptions": {
    "target": "es2015",
    "lib": ["es2015"],
    "types": ["node"] 
  },
  "include": ["tree-sitter.d.ts"] 
}

This configuration tells Typedoc:

• target and lib : To use the ES2015 features required by your .d.ts file (like Symbol.iterator ).
• types : To include type definitions for Node.js, resolving the Buffer and Iterator errors.
• include : To specifically include your .d.ts file for processing.

2. Run Typedoc:

npx typedoc --tsconfig tsconfig.json

By specifying the --tsconfig flag, Typedoc will use the settings from your tsconfig.json file, resolving the type dependencies and generating the documentation.

Additional Tips:

• Customize Typedoc Output: Refer to the Typedoc documentation ( https://typedoc.org/ ) for customization options like output format (HTML, Markdown, JSON), themes, and more.
• No index.js Entry Point: Since you're documenting types from a .d.ts file, you don't need to specify an entry point like index.js .
• Keep tsconfig.json Minimal: Include only the necessary settings in your tsconfig.json to avoid conflicts if you have other TypeScript projects.

This approach should generate your TypeScript API documentation correctly from the .d.ts file.