Typescript: Add JSDoc's @inheritDoc Support for Static Class Members for TypeScript

[CatGuardian]

TypeScript Version: 2.7.2

Search Terms:
IntelliSense
static
subclass
JSDoc
Class
Members
inheritDoc

Code

abstract class BaseClass {
  /**
   * Useful description always applicable
   * 
   * @returns {string} Useful description of return value always applicable.
   */
  public static doSomethingUseful(stuff?: any): string {
    throw new Error('Must be implemented by subclass');
  }

  /**
   * Applicable description always.
   */
  public static readonly someProperty: string = 'general value';
}




class SubClass extends BaseClass {

  /**
   * @inheritDoc
   * 
   * @param {{ tiger: string; lion: string; }} [mySpecificStuff] Description of my specific parameter.
   */
  public static doSomethingUseful(mySpecificStuff?: { tiger: string; lion: string; }): string {
    let useful = '';

    // do something useful to useful

    return useful;
  }

  /**
   * @inheritDoc
   */
  public static readonly someProperty: string = 'specific to this class value'
}

Expected behavior:
For someProperty I expect the JSDocs describes for BaseClass.someProperty to show up exactly for SubClass.someProperty

For doSomethingUseful(...) I expect the documentation that was provided for BaseClass.doSomethingUseful to show up for SubClass.doSomethingUseful. I also expect the extra documentation (the parameters in this case) for SubClass.doSomethingUseful to also show up in the intellisense documentation for SubClass.doSomethingUseful.

Actual behavior:
The actual behavior is that the static properties of SubClass is not getting inherited docs from BaseClass

Related Issues:

8912

7084

[mhegazy]

PRs welcomed.

[mhegazy]

Also pinging @sjbarag in case he would like to pick this one up.

[sjbarag]

Thanks for the mention @mhegazy! I should be able to get to this in the next week or so 🙂

@CatGuardian this is a great description — thanks for the detailed report ❤️

[sjbarag]

Some notes, mostly for myself but beneficial for anyone playing along at home:

• Inherited JSDoc comments are found in findInheritedJSDocComments, which uses typeChecker#getPropertyOfType to find a property in a parent class of the same name:

https://github.com/Microsoft/TypeScript/blob/4170f35abcec2710c4549d0b3a14d39dd9692988/src/services/services.ts#L556-L563

• Static class members are, surprisingly, exposed as exports on a Symbol:

https://github.com/Microsoft/TypeScript/blob/4170f35abcec2710c4549d0b3a14d39dd9692988/src/compiler/types.ts#L3360-L3376

• typeChecker#getPropetyOfType transitively depends on resolveObjectTypeMembers in checker.ts, which unfortunately _doesn't_ set the exports property on the ObjectType it receives:

  (unfortunately there's no fancy preview available because checker.ts is too big for GitHub :cry:)

As a type-checker n00b, it seems like resolveObjectTypeMembers should also consider a Symbol's exports and add them to the type it receives, but there's probably a Very Good Reason why that isn't already the case.

If anyone has any suggestions, I'd love to hear them! It's quite likely that I'm looking in the exact opposite direction I should be :man_shrugging:

[ghost]

@sjbarag Just dropping by to ask how far the implementation of this feature has come. In my current project I noticed that the parent documentation isn't being inherited and I'd really like to see this feature.

[sjbarag]

@NearAutomata I'm sorry about the lack of updates! A combination of work, side-projects, and general life stuff stole my attention away from this investigation. Things have settled back down, so I'm going to take another crack at it. If I make any progress I'll update this issue :smiley:

[pdufour]

Any workaround for this?