typedoc-readonly

Advanced support for Readonly in TypeDoc

typedoc-readonly is a plugin for TypeDoc dedicated to generating more fine-grained documentation for type aliases based on TypeScript's Readonly<>, as you can notice from this image:

Installation

1. Of course, typedoc is a fundamental prerequisite.

2. Then, you'll need to install the plugin package (usually, as a dev dependency) for your project:

   @giancosta86/typedoc-plugin

3. Finally, the plugin itself must be loaded into TypeDoc - for example, by adding this property to TypeDoc's configuration object:

   {
     plugin: ["@giancosta86/typedoc-readonly"],
   }

And that's all! TypeDoc will start generating more elegant documentation for your immutable types! 🥳

How it works

Basic rules

Whenever the plugin finds a type alias based on Readonly<> wrapping a type literal, as in:

/**
 * Plain, simple immutable type literal.
 */
export type Dodo = Readonly<{
  /**
   * The dodo's name.
   */
  name: string;

  /**
   * The dodo's age, in years.
   */
  years: number;
}>;

the declaration will be converted as if it were written like this:

/**
 * Plain, simple immutable type literal.
 */
export type Dodo = {
  /**
   * The dodo's name.
   */
  readonly name: string;

  /**
   * The dodo's age, in years.
   */
  readonly years: number;
};

As a consequence, TypeDoc will expand each property's description (if provided) - decorating it with a Readonly label.

On the other hand, Readonly<> wrappers around type names are left unaltered:

export type Bear = Readonly<MutableBear>;

Advanced rules

The algorithm also applies to intersection types; for example:

export type PolarBear = Bear &
  Readonly<{
    /**
     * The bear's location, according to some system.
     */
    coordinates: [number, number];

    /**
     * The bear's best friend.
     */
    bestFriend: Bear;
  }>;

will be documented as if it were declared:

export type PolarBear = Bear & {
  /**
   * The bear's location, according to some system.
   */
  readonly coordinates: [number, number];

  /**
   * The bear's best friend.
   */
  readonly bestFriend: Bear;
};

The same applies, of course, to union types:

export type YellowstoneAnimal =
  | PolarBear
  | Chipmunk
  | Readonly<{
      /**
       * The generic name for the animal.
       */
      genericName: string;
    }>;

will be interpreted like this:

export type YellowstoneAnimal =
  | PolarBear
  | Chipmunk
  | {
      /**
       * The generic name for the animal.
       */
      readonly genericName: string;
    };

Finally, it is interesting to note that the algorithm operates recursively - for instance, reducing:

export type Chipmunk = Readonly<
  Readonly<
    Readonly<{
      /**
       * The chipmunks's name.
       */
      name: string;

      /**
       * The chipmunk's age, in years.
       */
      years: number;
    }>
  >
>;

to:

export type Chipmunk = {
  /**
   * The chipmunks's name.
   */
  readonly name: string;

  /**
   * The chipmunk's age, in years.
   */
  readonly years: number;
};

For additional details about how the plugin internally works, you might want to set TypeDoc's logLevel to Verbose.

Further references

• TypeDoc - converts comments in TypeScript's source code into documentation

• Readonly<> - constructs a type with all properties of Type set to readonly