Support @hideconstructor JSDoc tag to hide constructors from classes.

[typhonrt]

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.

[Gerrit0]

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]

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]

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.

[typhonrt]

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]

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