How can I hide 'private' methods with JSDoc Typescript Declarations?

Question

Let's say I have a JavaScript class

/**
 * @element my-element
 */
export class MyElement extends HTMLElement {
  publicMethod() {}
  /** @private */
  privateMethod() {}
}

customElements.define('my-element', MyElement);

and a declaration file, generated using declaration and allowJs:

export class MyElement extends HTMLElement {
  publicMethod(): void;
  /** @private */
  privateMethod(): void
}

I also, in a post-build script, concat this to the declaration file:

declare global { interface HTMLElementTagNameMap { 'my-element': MyElement; } }

When using this element in a typescript file, I get access to privateMethod in autocomplete.

import 'my-element'
const me = document.createElement("my-element")
me.// autocompletes `privateMethod`

How can I instruct tsc to mark as private any methods, fields, or properties that are annotated with the @private JSDoc tag?

Answer 1

According to the JSDoc documentation, using /** @private */ is the correct syntax, but this is not how TypeScript handles it. You will need to leverage TypeScripts syntax to handle this, it will not work with JSDoc alone.

TypeScript 3.8 and up supports ES6 style private fields. You can denote a private field using the # symbol at the beginning of your method as such:

class Animal {
  #name: string;
  constructor(theName: string) {
    this.#name = theName;
  }
}

// example

new Animal("Cat").#name;
Property '#name' is not accessible outside class 'Animal' because it has a private identifier.

Alternatively, TypeScript also allows you to declare a field as private using the private marker and will provide the desired result. Doing this will not show the privateMethod during autocompletion (at least for it me it does not).

/**
 * @element my-element
 */
class MyElement extends HTMLElement {
  publicMethod() {}
  /** @private */
  private privateMethod() {}
}

let element = new MyElement()

element.privateMethod()
// Error: Property 'privateMethod' is private and only accessible within class 'MyElement'.

Here is an example of this working with VS Code intellisense.

Answer 2

Make sure you are using correct version of typescript. Typescript 3.8 added support for this, using Typescript 3.8 or heigher should support @private jsdoc modifier.

You can use tsc -h to get information about installed version of typescript compiler.