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?

Nitsew · Answer 1 · 2020-10-16T15:39:31.597

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.

If you use the `['privateMethod']` syntax, VS Code will autocomplete private methods — danwellman, Oct 28 '21 at 08:08

score 2 · Answer 2 · answered Oct 09 '20 at 18:22

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.

answered Oct 09 '20 at 18:22

Dipen Shah

25,562
1
32
58

I just tried with TypeScript `4.0.3`: doing `@private` on a function argument doesn't hide it from IntelliSense. – brillout Oct 09 '20 at 20:38
@brillout 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: https://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. – Dipen Shah Oct 10 '20 at 00:36
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: https://github.com/reframejs/wildcard-api/blob/32b15b73720b50530da743cebc60a3e8f928e345/server/WildcardServer.ts#L115-L118 – brillout Oct 10 '20 at 11:13
Ah I see, sorry I wasn't aware about that. May be you want to add feature request to typescript repo on github? – Dipen Shah Oct 10 '20 at 14:36

score -1 · Answer 3 · answered Jan 27 '20 at 06:29

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

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 https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html. — Justin Grant, Sep 13 '20 at 03:52

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

3 Answers3

Related