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

What is the best way to merge arrays within two objects and combine them together?

Getting a product by its slug can be achieved with Next.js 14 and Sanity by utilizing the capabilities

Toggling multiple ions simultaneously does not function independently

Best resolutions and formats for Nativescript-Vue application icons

What is the best way to remove table cells from a TableBody?

Basic JavaScript string calculator

The comparison between StrictNullChecks and Union Types in terms of syntax usage

Is it universally compatible to incorporate custom attributes through jquery metadata plugin in all web browsers?

Animating multiple elements in Angular 2 using a single function

Unable to establish a hyperlink to specific section of page using MUI 5 Drawer

Ensuring validity using dynamic context objects within Joi

HTMLMediaElement does not have the setSinkId method

Creating NextJS Route with Dynamic Links for Main Page and Subpages

How can one discern the most effective method to identify JavaScript code that alters particular HTML content on a webpage?

React - Updating the Color of a Specific Div within a Map Component

When utilizing :id with Vue, HTML attributes become hidden from view

The concept of setTimeout and how it affects binding in JavaScript

How can I take a screenshot from the client side and save it on the server side using PHP?

Don't forget to retain the checkboxes that were chosen in the

development of MapLayers with rails and javascript