Add codemod to propagate JSDoc comments to dual signatures

[IMax153]

Type

• Refactor
• Feature
• Bug Fix
• Optimization
• Documentation Update

Description

Problem Statement

At the moment, JSDoc annotations are lost the second that a user actually calls a method from the library.

When just inspecting methods as variables, you see the JSDoc on hover:

Effect.flatMap // <- JSDoc can be seen on hover

But the second you call the method, the JSDoc disappears:

Effect.flatMap( // <- JSDoc lost on hover

// or

Effect.void.pipe(
  Effect.flatMap( // <- JSDoc lost on hover
)

This is because the JSDoc trivia is associated with the parent variable declaration but they are not propagated to the inner call expression nodes.

Solution

This PR introduces a codemod which will traverse public package entrypoints and attempt to propagate JSDoc comments from the root of an export declaration into the dual call signatures.

Effectively this:

/**
 * A comment on a variable statement with a type literal annotation.
 * 
 * @since 1.0.0
 * @category constructors
 */
export const foo: {
  (arg: number): (self: string) => void
  (self, arg: number): void
} = {}

export declare function dual<A, B>(): void

/**
 * A comment on a variable statement with a call expression containing
 * a dual method.
 * 
 * @since 1.0.0
 * @category constructors
 */
export const bar = dual<
  (arg: number) => (self: string) => void
  (self, arg: number) => void
>()

becomes this:

/**
 * A comment on a variable statement with a type literal annotation.
 * 
 * @since 1.0.0
 * @category constructors
 */
export const foo: {
  /**
   * A comment on a variable statement with a type literal annotation.
   * 
   * @since 1.0.0
   * @category constructors
   */
  (arg: number): (self: string) => void
  /**
   * A comment on a variable statement with a type literal annotation.
   * 
   * @since 1.0.0
   * @category constructors
   */
  (self, arg: number): void
} = {}

export declare function dual<A, B>(): void

/**
 * A comment on a variable statement with a call expression containing
 * a dual method.
 * 
 * @since 1.0.0
 * @category constructors
 */
export const bar = dual<
  /**
   * A comment on a variable statement with a call expression containing
   * a dual method.
   * 
   * @since 1.0.0
   * @category constructors
   */
  (arg: number) => (self: string) => void
  /**
   * A comment on a variable statement with a call expression containing
   * a dual method.
   * 
   * @since 1.0.0
   * @category constructors
   */
  (self, arg: number) => void
>()

NOTE: if the node already contains comments, the codemod will NOT override them.

The codemod is only run in CI to avoid polluting the codebase with unnecessary JSDocs.

In addition, it is run before the build step to ensure that the build output will contain the JSDoc trivia that was added by the codemod.

Related

• Related Issue #
• Closes #

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0b659f1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR