TypeScript接口属性的jsdoc

Question

我有一个 TypeScript 接口，其中包含一个单字符属性名称（一个设计约束）。我想使用 JSDoc 注释这个接口，以帮助在 vscode 中进行自动完成。

这是当前的接口：

export interface ISource {
    b: string
    d: string
    f: string
    h: string
    M: number
    L: number
    P: number
    n: string
    r: string
    u: string
    p: string
}

无效的尝试包括：

/**
* @typedef {object} ISource
* @property {string} ISource.b - Bias: bias_text[rating.bias[0]],
* @property {string} ISource.d - Domain: rating.domain.replace(/^www\./, ""),
* @property {string} ISource.f - FacebookUrl: _.lowerCase(rating.facebook_url),
* @property {string} ISource.h - Host: `https://${rating.domain}`,
* @property {number} ISource.M - MozRankUrl: rating.moz_rank_url,
* @property {number} ISource.L - MozLinks: rating.moz_links,
* @property {number} ISource.P - MozPopularity: rating.moz_popularity,
* @property {string} ISource.n - Source: rating.source,
* @property {string} ISource.r - Reporting: _.upperCase(_.kebabCase(_.first(rating.factual_reporting))),
* @property {string} ISource.u - Url: url,
* @property {string} ISource.p - Path: path,
*/

export interface ISource {
    b: string
    d: string
    f: string
    h: string
    M: number
    L: number
    P: number
    n: string
    r: string
    u: string
    p: string
}

and

export interface ISource {
    b: string /** @property {string} b - Bias: bias_text[rating.bias[0]], */;
    d: string /** @property {string} d - Domain: rating.domain.replace(/^www\./, ""), */;
    f: string /** @property {string} f - FacebookUrl: _.lowerCase(rating.facebook_url), */;
    h: string /** @property {string} h - Host: `https://${rating.domain}`, */;
    M: number /** @property {string} M - MozRankUrl: rating.moz_rank_url, */;
    L: number /** @property {string} L - MozLinks: rating.moz_links, */;
    P: number /** @property {string} P - MozPopularity: rating.moz_popularity, */;
    n: string /** @property {string} n - Source: rating.source, */;
    r: string /** @property {string} r - Reporting: _.upperCase(_.kebabCase(_.first(rating.factual_reporting))), */;
    u: string /** @property {string} u - Url: url, */;
    p: string /** @property {string} p - Path: path, */;
}

- Mike Crowe

Answer 1

只需在每个属性之前放置文档注释：

export interface ISource {
    /**
     * Bias: bias_text[rating.bias[0]],
     */
    b: string

    /**
     * Domain: `rating.domain.replace(/^www\./, "")`
     */
    d: string
    ...
}

（此外，在TS文件中的JSDocs中不要使用类型注释；编译器和工具将忽略这些类型）

- Matt Bierner

---

有没有其他替代方案，比如使用函数@param？这样可以使属性定义更简洁。 - wolfram77

您可以将注释格式化为单行： /** 文档在这里 */ b: string - Matt Bierner

有没有一种方法可以在多个类型之间共享注释？我有三个类型定义，它们都具有相同的属性。这用于覆盖。我不想在所有三个类型定义上复制粘贴相同的文档。 - user1015434

听起来你应该使用继承 @user1015434 - Noah Tatko

在这种情况下，继承是行不通的。我有7种不同的类型变体，基于propA，您只能为propB选择特定的值。但是，与propA相关的文档对所有7种类型变体都是相同的。 - user1015434

@user1015434 你可以直接使用@see和@link。另外，关于提出的建议，继承不好，组合更好。继承总是创建复杂的原型链，而且在许多情况下并不是最合适的概念，除非你每天都只了解和使用面向对象编程，对其他东西不熟悉。也有@borrows，也许这个描述听起来就是为这个而做的（https://jsdoc.app/tags-borrows.html） - undefined