Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add JSDoc's @inheritDoc Support for Static Class Members for TypeScript #23215

Closed
CatGuardian opened this issue Apr 6, 2018 · 7 comments · Fixed by #46719
Closed

Add JSDoc's @inheritDoc Support for Static Class Members for TypeScript #23215

CatGuardian opened this issue Apr 6, 2018 · 7 comments · Fixed by #46719
Labels
Bug A bug in TypeScript Domain: JSDoc Relates to JSDoc parsing and type generation Help Wanted You can do this
Milestone

Comments

@CatGuardian
Copy link

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 mhegazy added Bug A bug in TypeScript Domain: JSDoc Relates to JSDoc parsing and type generation Help Wanted You can do this labels Apr 6, 2018
@mhegazy mhegazy added this to the Community milestone Apr 6, 2018
@mhegazy
Copy link
Contributor

mhegazy commented Apr 6, 2018

PRs welcomed.

@mhegazy
Copy link
Contributor

mhegazy commented Apr 6, 2018

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

@sjbarag
Copy link
Contributor

sjbarag commented Apr 7, 2018

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
Copy link
Contributor

sjbarag commented Apr 7, 2018

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 😢)

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 🤷‍♂️

@ghost
Copy link

ghost commented Apr 26, 2018

@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
Copy link
Contributor

sjbarag commented Apr 27, 2018

@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 😃

@RyanCavanaugh RyanCavanaugh modified the milestones: Community, Backlog Mar 7, 2019
@pdufour
Copy link

pdufour commented Mar 3, 2020

Any workaround for this?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Bug A bug in TypeScript Domain: JSDoc Relates to JSDoc parsing and type generation Help Wanted You can do this
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants