TypeScript泛型函数options参数JSDoc注释无法全部显示问题

问题分析 #

你遇到的核心问题是：GetOptions作为联合类型，其成员虽继承自Get接口，但IDE在处理泛型参数的交叉类型时，无法自动向上查找父接口的属性注释，导致maxAge、decrypt这类继承属性的注释丢失。

可行解决方案 #

方案1：用交叉类型重构子类型，保留注释 #

将原本的接口继承改为交叉类型，让子类型直接携带父接口的属性及注释，避免IDE依赖继承链查找注释：

type TransformOptions = 'auto' | 'binary' | 'json';

interface Get {
    /**
     * How long to keep the value in cache
     */
    maxAge?: number
    /**
     * Whether to decrypt the param or not
     */
    decrypt?: boolean
    /**
     * Whether to transform the param or not
     */
    transform?: TransformOptions
}

// 用交叉类型代替接口继承，直接保留Get的属性注释
type GetTransformJson = Get & {
    /**
     * Whether to transform the param or not (json)
     */
    transform?: 'json'
}

type GetTransformNo = Get & {
    transform?: never
}

type GetOptions = GetTransformNo | GetTransformJson | undefined;

type RetType<O = undefined> =
    undefined extends O ? string :
    O extends GetTransformNo ? string :
    O extends GetTransformJson ? Record<string, any> :
    never;

函数签名保持你修改后的版本即可：

declare function apiCall(name: string): Promise<string>;

const getParameters = async <O extends GetOptions | undefined = undefined>(
    name: string,
    options?: O & GetOptions
): Promise<RetType<O> | undefined> => {
    const value = await apiCall(name);

    if (options?.transform === 'json') {
        const parsed = JSON.parse(value);
        return parsed as RetType<O>;
    } else {
        return value as RetType<O>;
    }
}

方案2：显式关联父接口属性到参数类型 #

如果不想修改原有类型定义，可以在函数参数类型中显式引入Get的属性，强制IDE加载对应注释：

const getParameters = async <O extends GetOptions | undefined = undefined>(
    name: string,
    options?: O & Pick<Get, 'maxAge' | 'decrypt'>
): Promise<RetType<O> | undefined> => {
    // 实现代码不变
}

原理说明 #

TypeScript IDE（如VS Code）对联合类型的注释识别依赖于类型的显式属性定义，而非继承链。用交叉类型重构子类型后，maxAge、decrypt等属性会直接存在于每个联合成员中，IDE能正确读取并显示对应的JSDoc注释；显式关联父接口属性的方式，则是直接将注释来源引入参数类型，绕过联合类型的查找限制。

内容的提问来源于stack exchange，提问作者Andre.IDK