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

Support @hideconstructor JSDoc tag to hide constructors from classes. #2577

Closed
typhonrt opened this issue May 22, 2024 · 5 comments
Closed
Labels
enhancement Improved functionality
Milestone

Comments

@typhonrt
Copy link

For classes that have only static methods presently there is no clean way to prevent TypeDoc from adding a default constructor to docs generated. This feature proposal suggests that the JSDoc tag @hideconstructor is useful. There is not an equivalent tag in TSDoc as far as I'm aware.

/**
 * This class should not be constructed as it only contains static methods.
 * 
 * @hideconstructor
 */
export class StaticClass {
   static foo() { ... }
}

This tag can also be applied on constructors as well per the JSDoc description.


TSC won't output default constructors even if they have comments / JSDoc attached to them.

The only non-clean workaround that I've found is to provide a constructor with a parameter and use the @hidden tag to remove it from documentation. This is very non-clean because in generated type declarations the dummy constructor is exposed.


I can take a look at a PR for this if you are too busy as this feature improves the API docs for libraries I release.

@typhonrt typhonrt added the enhancement Improved functionality label May 22, 2024
@Gerrit0
Copy link
Collaborator

Gerrit0 commented May 24, 2024

That's no class, it's a namespace in disguise!

Because of that, it should really have a private constructor, which TS will emit in declaration files.

export class StaticClass {
   private constructor() {}
   static foo() { ... }
}

If --excludePrivate is set, that'll result in the constructor automatically being hidden, and removes the need for the clarifying comment as the type system enforces the desired behavior.


A search on GitHub shows this is used 9.1k times, which is more than I expected, but still much less than the 123k for @ignore / 56.9k for @hidden

It feels like usage of this tag would really indicate something else is wrong to me... that said, that's the state of JS in general, so I'm begrudgingly starting to think that TypeDoc should support this...


(wait, what, --excludePrivate defaults to false?! going to change that with 0.26...)

@typhonrt
Copy link
Author

typhonrt commented May 24, 2024

While I do have some projects / repos that use Typescript the bulk of my efforts are ESM oriented and I generate public API type declarations from ESM code w/ JSDoc, etc. In this case there is no way to mark classes with only static methods as having no constructor. Even if a constructor with no parameters is present with JSDoc that has @private it is not included in the public type declarations that TSC generates. I'm generating API docs from type declarations and not source code. TSC will preserve JSDoc comments for class declarations and this is where @hideconstructor would be located in this case.

I can create a plugin for this, but do think there is a case in supporting @hideconstructor in the ESM -> type declarations -> API docs work flow as it has applications for when public type declarations are used to generate docs.

I would be glad to submit a PR for this use case vs plugin. What I'd probably do is roll this feature in the DMT theme if you decide that this is not worth supporting in TypeDoc itself. It's not a whole lot of code to support this feature.

@Gerrit0
Copy link
Collaborator

Gerrit0 commented May 24, 2024

That behavior definitely smells like a bug to me. TypeScript is incorrectly representing the type of your class in the declaration file. Possible I'm missing something, we'll see what the TS team says

It's an easy patch to add it, so I went ahead and did it, but will definitely be discouraging its use in the documentation.

@Gerrit0 Gerrit0 added this to the v0.26.0 milestone May 24, 2024
@typhonrt
Copy link
Author

typhonrt commented May 24, 2024

Thanks for following up with the issue in the TS repo. Indeed this definitely seems like a TS issue and if resolved would serve the purpose far better than @hideconstructor. I also just noticed that if one does the following and doesn't add @param for the bogus parameter _invalid that it will generate desired types:

export class StaticClass {
   /**
    * @private
    */
   constructor(_invalid) {
      throw new Error('This is a static class and should not be constructed.');
   }
}
declare class StaticClass {
  /**
   * @private
   */
  private constructor();
}

@Gerrit0 Gerrit0 mentioned this issue Jun 1, 2024
7 tasks
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Jun 16, 2024

Included in TypeDoc 0.26, which is releasing 2024/06/21

@Gerrit0 Gerrit0 closed this as completed Jun 16, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Improved functionality
Projects
None yet
Development

No branches or pull requests

2 participants