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?

Barby

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.

Annelleannemarie

If you use the ['privateMethod'] syntax, VS Code will autocomplete private methods – Labium

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.

Willawillabella

I just tried with TypeScript 4.0.3: doing @private on a function argument doesn't hide it from IntelliSense. – Vituline

@Vituline I am not sure, I checked in my workspace with 4.03 and it seems working. I have added this stackblitz, if you can take a look: stackblitz.com/edit/typescript-gygcmw. I have my-element.js with same declaration as you and test.ts where I am trying to use MyElement and vscode does not expose private variable and method there. – Willawillabella

Your example shows a private class method - what I'm trying to do is to hide a function argument from IntelliSense. (OP asked about private class methods hence I will reward you the bounty.) Concretely: I'm trying to hide __INTERNAL_universalAdapter from the user: github.com/reframejs/wildcard-api/blob/… – Vituline

Ah I see, sorry I wasn't aware about that. May be you want to add feature request to typescript repo on github? – Willawillabella

Answer 3

You need to use @ignore annotation for those methods and classes you wish to exclude from documenting.

The @ignore tag indicates that a symbol in your code should never appear in the documentation.

/**
 * @class
 * @ignore
 */
function Jacket() {
    /** The jacket's color. */
    this.color = null;
}

/**
 * @namespace
 * @ignore
 */
var Clothes = {
    /**
     * @class
     * @ignore
     */
    Jacket: function() {
        /** The jacket's color. */
        this.color = null;
    }
};

More on this here: https://jsdoc.app/tags-ignore.html

Nonagon

FYI - as of 2020-09-12, the @ignore JSDoc tag is not supported by VS Code. You can add it to a type declaration but VSCode doesn't actually hide that type from IntelliSense autocomplete. See typescriptlang.org/docs/handbook/jsdoc-supported-types.html. – Lafrance