chore: add @function tags to all arrow functions #15
Conversation
This stack of pull requests is managed by Graphite. Learn more about stacking. |
There was a problem hiding this comment.
Pull request overview
This PR introduces a standardized documentation practice by adding @function tags to all arrow functions throughout the codebase. The change includes a custom ESLint rule to enforce this convention going forward, ensuring consistency in JSDoc comments for arrow functions.
- Added a new custom ESLint rule to require
@functiontags in JSDoc comments for named arrow functions - Applied
@functiontags to all existing arrow functions across source files, tests, and configuration - Updated cspell configuration to recognize new terminology
Reviewed changes
Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
.config/require-function-tag-in-arrow-functions.js |
New custom ESLint rule implementation to enforce @function tags in arrow function JSDoc comments |
eslint.config.js |
Configured the new custom rule with options to require tags for named functions |
src/bargs.ts |
Added @function tags to arrow functions including transform composition helpers |
src/help.ts |
Added @function tags to utility functions for help generation |
src/osc.ts |
Added @function tags to terminal hyperlink support functions |
src/opt.ts |
Added @function tags to option and positional builder functions |
src/parser.ts |
Added @function tags to parsing and coercion functions |
src/theme.ts |
Added @function tags to theme and styling utility functions |
src/validate.ts |
Added @function tags to validation and type guard functions |
src/version.ts |
Added @function tags to version detection and package.json utilities |
test/bargs.test.ts |
Added @function tags to test helper functions |
cspell.json |
Updated spelling dictionary with "TSES" and moved "ghostty" to ignoreWords |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| /** | ||
| * ESLint rule to require `@function` tag in JSDoc comments for arrow functions | ||
| * | ||
| * This rule enforces the presence of `@function` tags in JSDoc comments for | ||
| * arrow functions to improve code documentation and maintain consistency with | ||
| * the project's documentation standards. | ||
| * | ||
| * The rule supports: | ||
| * | ||
| * - Named arrow functions (`const foo = () => {}`) | ||
| * - Arrow functions in object properties (`{ method: () => {} }`) | ||
| * - Arrow functions in assignments (`obj.method = () => {}`) | ||
| * - Export declarations (`export const foo = () => {}`) | ||
| * | ||
| * Configuration options: | ||
| * | ||
| * - `requireForNamed`: Whether to require `@function` tags for named arrow | ||
| * functions (default: `true`) | ||
| * - `requireForAnonymous`: Whether to require `@function` tags for anonymous | ||
| * arrow functions (default: `false`) | ||
| */ |
There was a problem hiding this comment.
The documentation comment on lines 16-36 duplicates the comment at lines 1-5. The first comment is a package documentation comment, while the second one appears to be describing the same thing. This duplication creates unnecessary redundancy.
| /** | |
| * ESLint rule to require `@function` tag in JSDoc comments for arrow functions | |
| * | |
| * This rule enforces the presence of `@function` tags in JSDoc comments for | |
| * arrow functions to improve code documentation and maintain consistency with | |
| * the project's documentation standards. | |
| * | |
| * The rule supports: | |
| * | |
| * - Named arrow functions (`const foo = () => {}`) | |
| * - Arrow functions in object properties (`{ method: () => {} }`) | |
| * - Arrow functions in assignments (`obj.method = () => {}`) | |
| * - Export declarations (`export const foo = () => {}`) | |
| * | |
| * Configuration options: | |
| * | |
| * - `requireForNamed`: Whether to require `@function` tags for named arrow | |
| * functions (default: `true`) | |
| * - `requireForAnonymous`: Whether to require `@function` tags for anonymous | |
| * arrow functions (default: `false`) | |
| */ |
| if ( | ||
| parent?.type === AST_NODE_TYPES.VariableDeclarator && | ||
| parent.parent?.parent?.type === AST_NODE_TYPES.ExportNamedDeclaration | ||
| ) { | ||
| return true; | ||
| } | ||
|
|
There was a problem hiding this comment.
The shouldRequireTag function checks for exported variables in lines 103-108, but this condition is redundant. Lines 85-90 already check for VariableDeclarator with an identifier. The export check at lines 103-108 will never be reached because if the parent is a VariableDeclarator, the function returns true at line 89 before reaching line 103.
| if ( | |
| parent?.type === AST_NODE_TYPES.VariableDeclarator && | |
| parent.parent?.parent?.type === AST_NODE_TYPES.ExportNamedDeclaration | |
| ) { | |
| return true; | |
| } |
| "frickin" | ||
| "frickin", | ||
| "TSES", | ||
| "ghostty" |
There was a problem hiding this comment.
The word "ghostty" is being moved from the "words" array to the "ignoreWords" array. According to cspell semantics, "words" are considered valid dictionary words while "ignoreWords" are words that should be ignored but not necessarily considered valid. If "ghostty" is a legitimate term (e.g., a terminal emulator name), it should remain in "words" rather than being moved to "ignoreWords".
(this is for typedoc)