如何為具有擴展接口的泛型類型的函數參數做 TypeScript tsdoc 文檔？

Question

考慮以下代碼，注意someField的文檔：

interface Test {
    /**
     * Some description.
     * lorum ipsum.
     * foo bar.
     */
    someField: string;
}

function withGeneric<T extends Test>(arg: T) {
    return arg;
}

function withoutGeneric(arg: Test) {
    return arg;
}

withGeneric({
    someField: ""
});

withoutGeneric({
    someField: ""
});

當我懸停我的鼠標someField在withoutGeneric通話，VSCode很好地顯示我的文檔：

但是，在withGeneric調用someField懸停在someField時，不會顯示文檔：

有沒有辦法使 tsdoc 文檔也與通用參數一起使用？

Answer 1

考慮到當您創建內聯對象時，它的類型不是Test ：

const config = {
    someField: ""
};

根據定義，您的withoutGeneric函數采用Test類型的參數，因此 TypeScript 可以推斷屬性類型。 但是，當您的函數是泛型但您沒有顯式設置泛型類型時，TypeScript 將從內聯對象的類型推斷泛型類型，這只是您在上面看到的默認推斷類型。

您可以在智能感知中看到這一點：

TypeScript 將泛型類型推斷為{ someField: string; } { someField: string; } . 這滿足了Test接口的要求，但是值是它自己推斷的默認類型，而不是Test 。

考慮以下示例：

interface Foobar {
    /**
     * Unrelated doc string
     */
    someField: string;
}

const config:Foobar = {
    someField: ""
}

您將獲得以下智能感知：

請注意， Foobar類型滿足withGeneric函數，因為它具有所需的屬性並且它們是正確的類型。 但是，與someField關聯的文檔字符串將是Unrelated doc string因為這是config變量的類型。

如果您顯式設置函數的泛型類型，那么它會按您的預期運行。

withGeneric<Test>({
    someField: ""
});

產生以下結果：

如果您明確地將類型設置為Foobar ，那么您將獲得 Foobar 的文檔字符串：

withGeneric<Foobar>({
    someField: ""
});

產量：

Answer 2

我找到了一個適合我的目的的答案。 添加具有擴展自類型的聯合：

/**
 * withGeneric sample
 * @typeParam T - must be a Test
 * @param arg 
 * @returns 
 */
function withGeneric<T extends Test>(arg: T & Test) {
    return arg;
}

現在 VSCode 確實顯示了文檔：

感覺就像一個把戲，但我看不出它有什么缺點？