Is there a way to conceal 'private' methods using JSDoc TypeScript declarations?

Question

Is there a way to conceal 'private' methods using JSDoc TypeScript declarations?

If we consider a scenario where there is a JavaScript class

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

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

along with a declaration file that has been generated using declaration and allowJs:

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

In addition, as part of a post-build script, this is concatenated to the declaration file:

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

Now, when utilizing this element in a TypeScript file, accessing privateMethod is available in autocomplete.

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

The question arises on how to direct tsc to designate any methods, fields, or properties marked with the @private JSDoc tag as private?

javascript typescript private jsdoc .d.ts

Answer 1

Answer №1

As stated in the JSDoc documentation, the correct syntax for marking a private field is `/** @private */`, however, TypeScript does not handle it this way. To work with private fields in TypeScript, you need to use TypeScript's specific syntax and cannot rely on JSDoc alone.

Starting from TypeScript 3.8, ES6 style private fields are supported. You can indicate a private field by using the `#` symbol at the beginning of your method like this:

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 designate a field as private by using the `private` keyword, which will achieve the desired outcome. By doing this, the `privateMethod` will not be displayed during autocompletion (at least, it doesn't for me).

/**
 * @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 demonstrating how this works with VS Code intellisense.

https://i.stack.imgur.com/kNoUb.gif

Answer 2

As stated in the JSDoc documentation, the correct syntax for marking a private field is `/** @private */`, however, TypeScript does not handle it this way. To work with private fields in TypeScript, you need to use TypeScript's specific syntax and cannot rely on JSDoc alone.

Starting from TypeScript 3.8, ES6 style private fields are supported. You can indicate a private field by using the `#` symbol at the beginning of your method like this:

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 designate a field as private by using the `private` keyword, which will achieve the desired outcome. By doing this, the `privateMethod` will not be displayed during autocompletion (at least, it doesn't for me).

/**
 * @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 demonstrating how this works with VS Code intellisense.

https://i.stack.imgur.com/kNoUb.gif

Answer 3

Answer №2

Ensure you have the correct version of TypeScript installed. Version 3.8 introduced support for this feature, so using Typescript 3.8 or newer should enable the @private JSDoc modifier.

To check the version of your TypeScript compiler, you can use the command tsc -h.

Answer 4

Ensure you have the correct version of TypeScript installed. Version 3.8 introduced support for this feature, so using Typescript 3.8 or newer should enable the @private JSDoc modifier.

To check the version of your TypeScript compiler, you can use the command tsc -h.

Answer 5

Answer №3

To exclude certain methods and classes from documentation, you should use the @ignore annotation.

When you add the @ignore tag to a symbol in your code, it will not be included in the documentation.

/**
 * @class
 * @ignore
 */
function Shoes() {
    /** The shoes' size. */
    this.size = null;
}

/**
 * @namespace
 * @ignore
 */
var Accessories = {
    /**
     * @class
     * @ignore
     */
    Wallet: function() {
        /** The wallet's color. */
        this.color = null;
    }
};

For more information, visit:

Answer 6

To exclude certain methods and classes from documentation, you should use the @ignore annotation.

When you add the @ignore tag to a symbol in your code, it will not be included in the documentation.

/**
 * @class
 * @ignore
 */
function Shoes() {
    /** The shoes' size. */
    this.size = null;
}

/**
 * @namespace
 * @ignore
 */
var Accessories = {
    /**
     * @class
     * @ignore
     */
    Wallet: function() {
        /** The wallet's color. */
        this.color = null;
    }
};

For more information, visit:

Is there a way to conceal 'private' methods using JSDoc TypeScript declarations?

Answer №1

Answer №2

Answer №3

Similar questions

Learn how to configure your Angular uib-typeahead to display suggestions as soon as the model is bound

What is the best way to present JSON data retrieved from an API on different pages using Next.js?

Transform HTML elements within an *ngFor iteration based on a specific variable in Angular 4

Collapse dropdown menus upon clicking outside of them

The Art of JavaScript Module Patterns in Image Sliders

Directive unable to recognize ng-pattern functionality

Data transmission is only possible when the connection is in the 'Connected' state

Firefox does not support the event

Add a unique CSS style to both text and image using anchor tags

Saving a complicated schema in Node using Mongoose fails to save or update when encountering an error

The offline functionality of the Angular Progressive Web App(PWA) is experiencing difficulties

Utilizing Angular 2 to retrieve and assign object properties provided by a service to a local variable within a

Efficient Searching with Typescript and Lodash: Boosting Performance with Arrays and Objects

Implementing Shader Effects around Mouse using Three.js

Adapting the current codebase to be compatible with Typescript

Getting URL Parameters in Angular JS

Using JavaScript to dynamically write content to the document in the

How can I trigger a method after the user has finished selecting items in a v-autocomplete with multiple selection using Vuetify?

Using a package with `webfontloader` in NextJs for Server-Side Rendering: A guide

Incorporating HTML into the Ajax Response