用于接口属性的 TypeScript jsdoc

Posted 2023-03-13

【中文标题】用于接口属性的 TypeScript jsdoc

【英文标题】：TypeScript jsdoc for interface properties

【发布时间】：2020-02-21 20:24:09

【问题描述】：

我有一个带有单字符属性名称（设计约束）的 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

和

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, */;

【参考方案1】：

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

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

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

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

【讨论】：

是否有替代方法，例如函数@param。这使得属性定义很长。

您可以将评论格式化为单行：/** Docs here */ b: string