Generate documentation based on type definition file

[jens-duttke]

Search terms

type definition

Expected Behavior / Actual Behavior

In version 0.19.2 I was able to use a *.d.ts file (containing a declare module '...' { ... }) as source of the documentation.
After updating to version 0.20.1 the generated documentation, based on the same file is empty.

Is there a new way to get a documentation generated based on type definition files, instead of the actual source code (which works, but my type definition file contains a lot more details).

Steps to reproduce the bug

My previous TypeDoc configuration (till 0.19.2):

{
	"name": "HexEd.it",
	"readme": "none",
	"inputFiles": [
		"src/typings-bundle/ts4.0/main.d.ts"
	],
	"mode": "file",
	"out": "build/docs",
	"includeDeclarations": true,
	"excludeExternals": true,
	"excludeNotExported": true,
	"excludePrivate": true,
	"excludeProtected": true,
	"ignoreCompilerErrors": true,
	"disableSources": true,
	"listInvalidSymbolLinks": true
}

My new TypeDoc configuration:

{
	"name": "HexEd.it",
	"entryPoints": [
		"src/typings-bundle/ts4.0/main.d.ts"
	],
	"out": "build/docs",
	"excludeExternals": true,
	"excludePrivate": true,
	"excludeProtected": true,
	"disableSources": true,
	"listInvalidSymbolLinks": true,
	"markedOptions": {
		"mangle": false
	}
}

The type definition file:

declare module 'hexedit' {
	export interface Foo {
		foo: string;
	}

	export interface Bar {
		bar: number;
	}
}

My tsconfig.json

{
	"compilerOptions": {
		// General settings for code interpretation
		"target": "esnext",
		"module": "commonjs",
		"jsx": "react",
		"isolatedModules": true,
		"allowSyntheticDefaultImports": false,
		"experimentalDecorators": true,
		"noEmit": true,
		"noEmitOnError": true,

		"baseUrl": "./src",
		"rootDir": "src/ts",

		"paths": {
			/* ... */
		},

		// General settings for code generation
		"removeComments": false,
		"inlineSourceMap": true,
		"inlineSources": true,
		"newLine": "LF"
	},
	"include": [
		"./src/typings/*.d.ts",
		"./src/**/*"
	]
}

Environment

• Typedoc version: 0.20.1
• TypeScript version: 4.1.3
• Node.js version: v15.3.0
• OS: Windows 10 19042.685

[Gerrit0]

Hey, I didn't know HexEd.it used TypeDoc! Really useful tool :)

What does the output of this run look like? I copied your declaration file into a project and ran typedoc on it, which gave me this for the navigation:

Clicking on "hexedit" gives the expected output. 0.20.2 (soon, few more issues to check) adds some extra detection for modules of this style, which should give better results, omitting the "hexedit" namespace and including the types directly.

[jens-duttke]

Sorry for misleading you into the wrong direction.

I played around with my original type definitions, and figured out that the example I've posted above indeed works, and my problem is a bit more complex. I don't even know if it's my fault, or if it's a TypeDoc issue or an TypeScript issue.
Atleast I found a fix for my problem.

The source of my problem was that I have 2 type definition files, one for TS3.3+ and one for TS4.0+.

I don't know why it worked till TypeDoc 0.19, but now I had to add this to my tsconfig.json to fix the issue:

	"exclude": [
		"./src/typings-bundle/ts3.3/*.d.ts"
	]

If you are interested, I've created a Git repo now, with a minimal configuration to reproduce this issue:
https://github.com/jens-duttke/typedoc-issue

The only question is, why doesn't TypeDoc return an error message here, if it's not able to process the file correctly?
The type definition files seems to be correct.

[Gerrit0]

It looks like a fix included in 0.20.3 has fixed it - my logic for getting exports in global files was faulty. I upgraded to 0.20.4, and the output includes all of the types.

I am still somewhat surprised this works, needing to use // @ts-expect-error indicates a configuration error to me... though I haven't done much with declaration files. It seems like an appropriate typesVersions setup in package.json should make this work... but I played with it for a bit and wasn't able to get it to work.

[Gerrit0]

As far as I can tell this has been resolved, please reopen if I closed prematurely