Add missing documentation in testing.js#2399
Closed
itniuma2026 wants to merge 2 commits intoericcornelissen:mainfrom
Closed
Add missing documentation in testing.js#2399itniuma2026 wants to merge 2 commits intoericcornelissen:mainfrom
testing.js#2399itniuma2026 wants to merge 2 commits intoericcornelissen:mainfrom
Conversation
Add JSDoc documentation to the methods in `src/testing.js` that are currently undocumented. Fixes ericcornelissen#2396
This comment has been minimized.
This comment has been minimized.
ericcornelissen
added
the
documentation
ericcornelissen
changed the title
testing.jstesting.js
ericcornelissen
requested changes
Mar 5, 2026
Owner
ericcornelissen
left a comment
ericcornelissen
left a comment
There was a problem hiding this comment.
Lets try to align the wording with the real Shescape JSdoc, while still being honest that these implementations do different things.
Comment on lines
+89
to
+90
| * @param {object} [options] The options for escaping. | ||
| * @param {boolean | string} [options.shell] The shell to simulate. |
Owner
There was a problem hiding this comment.
This should be aligned with the docs for the Shescape constructor.
Suggested change
| * @param {object} [options] The options for escaping. | |
| * @param {boolean | string} [options.shell] The shell to simulate. | |
| * @param {object} [options] The escape options. | |
| * @param {boolean | string} [options.shell=true] The shell to escape for. |
| } | ||
|
|
||
| /** | ||
| * Take a single value and escape any dangerous characters. |
Owner
There was a problem hiding this comment.
Suggested change
| * Take a single value and escape any dangerous characters. | |
| * Take a single value, the argument, and pretend to escape it. |
| * | ||
| * @param {string} arg The argument to escape. | ||
| * @returns {string} The escaped argument. | ||
| * @throws {TypeError} If `arg` is not a stringable value. |
Owner
There was a problem hiding this comment.
Suggested change
| * @throws {TypeError} If `arg` is not a stringable value. | |
| * @throws {TypeError} The argument is not stringable. |
Comment on lines
+108
to
+109
| * Take an array of values and escape any dangerous characters in every | ||
| * element. |
Owner
There was a problem hiding this comment.
Suggested change
| * Take an array of values and escape any dangerous characters in every | |
| * element. | |
| * Take an array of values, the arguments, and pretend to escape every | |
| * argument. |
Comment on lines
+113
to
+114
| * @throws {TypeError} If `args` is not an array. | ||
| * @throws {TypeError} If any element of `args` is not a stringable value. |
Owner
There was a problem hiding this comment.
Suggested change
| * @throws {TypeError} If `args` is not an array. | |
| * @throws {TypeError} If any element of `args` is not a stringable value. | |
| * @throws {TypeError} The arguments are not an array. | |
| * @throws {TypeError} One of the arguments is not stringable. |
| } | ||
|
|
||
| /** | ||
| * Take a single value, quote it, and escape any dangerous characters. |
Owner
There was a problem hiding this comment.
Suggested change
| * Take a single value, quote it, and escape any dangerous characters. | |
| * Take a single value, the argument, and pretend to quote and escape it. |
Comment on lines
+126
to
+127
| * @throws {Error} If `shell` is set to `false`. | ||
| * @throws {TypeError} If `arg` is not a stringable value. |
Owner
There was a problem hiding this comment.
Suggested change
| * @throws {Error} If `shell` is set to `false`. | |
| * @throws {TypeError} If `arg` is not a stringable value. | |
| * @throws {TypeError} The argument is not stringable. | |
| * @throws {Error} Quoting is not supported with `shell: false`. |
Comment on lines
+138
to
+139
| * Take an array of values, quote every element, and escape any dangerous | ||
| * characters in every element. |
Owner
There was a problem hiding this comment.
Suggested change
| * Take an array of values, quote every element, and escape any dangerous | |
| * characters in every element. | |
| * Take an array of values, the arguments, and pretend to quote and escape | |
| * every argument. |
Comment on lines
+143
to
+145
| * @throws {Error} If `shell` is set to `false`. | ||
| * @throws {TypeError} If `args` is not an array. | ||
| * @throws {TypeError} If any element of `args` is not a stringable value. |
Owner
There was a problem hiding this comment.
Suggested change
| * @throws {Error} If `shell` is set to `false`. | |
| * @throws {TypeError} If `args` is not an array. | |
| * @throws {TypeError} If any element of `args` is not a stringable value. | |
| * @throws {TypeError} The arguments are not an array. | |
| * @throws {TypeError} One of the arguments is not stringable. | |
| * @throws {Error} Quoting is not supported with `shell: false`. |
| /** | ||
| * Always throws an error. | ||
| * | ||
| * @param {object} [_options] The options (ignored). |
Owner
There was a problem hiding this comment.
Suggested change
| * @param {object} [_options] The options (ignored). | |
| * @param {object} [_options] The escape options. |
Owner
|
@itniuma2026 are you open to addressing the requested changes? |
Owner
|
Closing this due a lack of responsiveness (in spite of the speed from issue-posted to pr-created, which was 6 minutes!) and a suspicion this is entirely LLM-generated (which I'm not necessarily against, but would explain the lack of a followup response). Please feel free to comment if you disagree and would still like to contribute :) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add JSDoc documentation to the methods in
src/testing.jsthat are currently undocumented.Approach
Examine the
src/testing.jsfile and add JSDoc comments to all exported class methods that lack documentation. The documentation should follow the same patterns used in the mainsrc/index.js(the Shescape class), describing parameters, return values, and thrown errors for methods likeescape,escapeAll,quote, andquoteAllin the testing stubs (Shescape, Stubscape, Throwscape, etc.).Files Changed
src/testing.jsRelated Issue
Fixes #2396
Testing
No tests were added with this change. Happy to add them if needed.