Comment Options

These options control how TypeDoc parses comments.

commentStyle

$ typedoc --commentStyle block

Determines what comment types TypeDoc will use. Note: Writing non-JSDoc comments will cause poorer intellisense in VSCode and is therefore generally not recommended.

Value	Behavior
jsdoc (default)	Use block comments starting with /**
block	Use all block comments
line	Use // comments
all	Use both block and line comments

useTsLinkResolution

$ typedoc --useTsLinkResolution false

Indicates that {@link} tags should be resolved with TypeScript's parsing rules. This is on by default.

preserveLinkText

$ typedoc --preserveLinkText false

Indicates whether or not {@link} tags should include just the name of the target reflection, or the original link text. This is on by default.

jsDocCompatibility

CLI:

$ typedoc --jsDocCompatibility false
$ typedoc --jsDocCompatibility.defaultTags false

typedoc.json (defaults):

{
    "jsDocCompatibility": {
        "exampleTags": true,
        "defaultTags": true,
        "inheritDocTag": true,
        "ignoreUnescapedBraces": true
    }
}

JSDoc specifies that the @example and @default tags indicate that the following content should be parsed as code. This conflicts with the TSDoc standard. With this option on, TypeDoc will attempt to infer from the tag content whether it should be parsed as code by checking if the tag content contains a code block.

TSDoc specifies that @inheritdoc should be spelled with a capitalized D, @inheritDoc. If inheritDocTag is set to false, TypeDoc will produce a warning when rewriting @inheritdoc to @inheritDoc.

TSDoc specifies that braces ({}) must be escaped within comments to avoid ambiguity between the start of an inline tag and a brace to be included in the rendered text. TypeDoc's ignoreUnescapedBraces option determines if warnings are emitted if a brace is found within regular comment text without being escaped.

suppressCommentWarningsInDeclarationFiles

$ typedoc --suppressCommentWarningsInDeclarationFiles

Prevents warnings due to unspecified tags from being reported in comments within .d.ts files.

blockTags

// typedoc.json
{
    "blockTags": ["@param", "@returns"]
}

This specifics all of the block tags that TypeDoc considers to be valid.

TypeDoc will warn when it finds an unknown tag. If you need to add a custom one, you can extend the defaults by using a JavaScript configuration file:

import { OptionDefaults } from "typedoc";

/** @type {Partial<import('typedoc').TypeDocOptions>} */
const config = {
    // Other config here.
    // ...

    blockTags: [...OptionDefaults.blockTags, "@foo"],
};

export default config;

Note that this option will be set by tsdoc.json, if present. (Using a tsdoc.json file is an alternate way to add a custom tag.)

Also see inlineTags and modifierTags.

inlineTags

// typedoc.json
{
    "inlineTags": ["@link"]
}

This specifics all of the inline tags that TypeDoc considers to be valid.

TypeDoc will warn when it finds a non-valid tag. If you need to add a custom one, you can extend the defaults by using a JavaScript configuration file:

import { OptionDefaults } from "typedoc";

/** @type {Partial<import('typedoc').TypeDocOptions>} */
const config = {
    // Other config here.
    // ...

    inlineTags: [...OptionDefaults.inlineTags, "@foo"],
};

export default config;

Note that this option will be set by tsdoc.json, if present. (Using a tsdoc.json file is an alternate way to add a custom tag.)

Also see blockTags and modifierTags.

modifierTags

// typedoc.json
{
    "modifierTags": ["@hidden", "@packageDocumentation"]
}

This specifics all of the modifier tags that TypeDoc considers to be valid.

TypeDoc will warn when it finds a non-valid tag. If you need to add a custom one, you can extend the defaults by using a JavaScript configuration file:

import { OptionDefaults } from "typedoc";

/** @type {Partial<import('typedoc').TypeDocOptions>} */
const config = {
    // Other config here.
    // ...

    modifierTags: [...OptionDefaults.modifierTags, "@foo"],
};

export default config;

Note that this option will be set by tsdoc.json, if present. (Using a tsdoc.json file is an alternate way to add a custom tag.)

Also see blockTags and inlineTags.

cascadedModifierTags

// typedoc.json
{
    "modifierTags": ["@alpha", "@beta", "@experimental"]
}

Specifies modifier tags which should be copied to all children of the parent reflection.

Note: @deprecated is a block tag, not a modifier tag, so should not be specified here.

excludeTags

$ typedoc --excludeTags apidefine

Specify tags that should be removed from doc comments when parsing. Useful if your project uses apiDoc for documenting RESTful web APIs.

externalSymbolLinkMappings

// typedoc.json
{
    // format: { [packageName: string]: { [exportName: string]: string } }
    "externalSymbolLinkMappings": {
        // {@link typescript!Partial} will use this link as well as
        // type Foo = Partial<Bar>
        "typescript": {
            "Partial": "https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype"
        }
    }
}

Can be used to specify locations of externally defined types. If the external library uses namespaces, qualify the name with . as a separator. These definitions will be used for both types linked to by the user via a {@link} tag and in code.

TypeDoc assumes that if a symbol was referenced from a package, it was exported from that package. This will be true for most native TypeScript packages, but packages which rely on @types will be linked according to the @types package, not the original module name. If both are intended to be supported, both packages must be listed.

// typedoc.json
{
    "externalSymbolLinkMappings": {
        // used by `class Foo extends Component {}`
        "@types/react": {
            "Component": "https://react.dev/reference/react/Component",
            // used if no other names match
            "*": "https://react.dev/"
        },
        // used by {@link react!Component}
        "react": {
            "Component": "https://react.dev/reference/react/Component"
        }
    }
}

Global external types are supported, but may have surprising behavior. Types which are defined in the TypeScript lib files (including Array, Promise, ...) will be detected as belonging to the typescript package rather than the special global package reserved for global types.

// typedoc.json
{
    "externalSymbolLinkMappings": {
        // used by {@link !Promise}
        "global": {
            "Promise": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise"
        },
        // used by type Foo = Promise<string>
        "typescript": {
            "Promise": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise"
        }
    }
}