TypeScript jsdoc for interface properties

Question

I have a TypeScript interface with a single-character property name (a design constraint). I would like to use JSDoc to document this interface to help with auto-complete in vscode.

Here's the current interface:

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
}

Non-working attempts are:

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

Matt Bierner · Accepted Answer · 2019-10-28 05:28:36Z

68

Just put the doc comment before each property:

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

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

(Also, don't use type annotations in JSDocs inside TS files; the compiler and tooling will ignore these types)

answered Oct 28, 2019 at 5:28

Matt Bierner

67.4k24 gold badges199 silver badges233 bronze badges

Sign up to request clarification or add additional context in comments.

6 Comments

wolfram77 Over a year ago

is there an alternative to this, like function @param. this makes the properties definition very long.

Matt Bierner Over a year ago

You can format the comment to be a single line: /** Docs here */ b: string

user1015434 Over a year ago

Is there a way to share a comment across multiple types? I have 3 type definitions that all have the same property. This is used for overriding. I don't want to have to copy paste the same documentation on all three type definitions

Noah Tatko Over a year ago

Sounds like you should be using inheritance @user1015434

user1015434 Over a year ago

Inheritance won’t work in this scenario. I have 7 different type variations were based on propA, you can only pick specific values for propB. But the documentation around propA is the same for all 7 type variations

|

Collectives™ on Stack Overflow

TypeScript jsdoc for interface properties

1 Answer 1

6 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

6 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related