Add JSDoc to @codemod-utils/ast-template

[ijlee2]

Background

In #77, I started adding JSDoc to @codemod-utils/files, so that end-developers have an additional reference for how the provided utilities work. This also provided me a chance to review existing code examples and see how they can be simplified (easier to understand).

I would like to see... 🙋‍♀️🙋‍♂️

Note

The package's README.md already has some documentation. Use the existing passages and code examples to get started.

Add JSDoc to the following utilities from @codemod-utils/ast-template:

1. tools (called AST in the consuming sites)

Why and how 💬

For each utility, add a JSDoc code block in the following format:

/**
 * Checks if a value is an odd number (not divisible by 2).
 *
 * @param value
 *
 * An integer (e.g. `-2`, `0`, `1`).
 *
 * @return
 *
 * Returns `true` if the value is an odd number.
 *
 * @example
 *
 * Checks if `5` is an odd number.
 *
 * ```ts
 * const someCondition = isOdd(5);
 * ```
 */
export function isOdd(value: number): boolean {
  return value % 2 === 1;
}

So the order of appearance is:

• Description (use short sentences and words that can be understood by many)
• Input(s)
• Output, if it exists (i.e. the return type is not void)
• Example(s)

Note

This package exports an object. For simplicity, we'll document the object as a whole, instead of adding JSDoc to each key of the object. The code example can be what is shown in What is it?.

How to test JSDoc

After adding the code block, find a place where the function is used. Possible places are:

• transformHandlebars()

When you hover over the function's name, you will see if the JSDoc shows up correctly (with regards to, for example, syntax highlight, code indentation).

How to fix formatting issues

Change the directory to the package's root, then run the lint:fix script.

cd packages/ast/template
pnpm lint:fix

How to create a pull request

This repo uses changesets to keep track of how package versions should be updated. Before you open a pull request, please add a changeset (indicate a minor version release) as your very last commit. (More information can be found in CONTRIBUTING.md.)

In your pull request, please provide a brief description, which explains the problem that you want to solve and how you solved it. As the problem concerns documentation, I may push an additional commit to your branch to edit passages, or ask for clarification and make suggestions.

References

• README for @codemod-utils/ast-template
• JSDoc added for @codemod-utils/files
• Annotations available in JSDoc
• JSDoc annotations supported by TypeScript