Docs Update: Improved Function and Class Descriptions #1895
Conversation
|
Has this been generated by OtterDoc? There are some potentially useful changes, but also several places where a new JSDoc is added instead of updated, comments in the code hoisted into the JSDoc, and |
|
@shadowspawn Yeah, these were generated using OtterDoc. We just started developing it and looking to get feedback and determine how useful people think it is. I'm wondering if people consider this too verbose with its additions? Yeah, it's hoisting some of the params up from the outer scope. That's probably not the desired way to document it. The Feedback welcome. Hope this PR could be massaged into being helpful as it's not perfect on the first pass. |
| * Sets the allowed choices for the argument and returns the current instance of the class. | ||
| * @param {Array} values - An array of allowed choices. | ||
| * @returns {Object} - The current instance of the class. | ||
| * @throws {InvalidArgumentError} - If the argument is not one of the allowed choices. |
There was a problem hiding this comment.
This routine contains a throw in the code, but does not actually throw an error that can be caught when it is called.
- The throw is in a custom
.parseArgfunction which is called later when the command-line arguments are being parsed. - The error is actually caught during processing and repackaged.
| @@ -26,6 +26,11 @@ class Help { | |||
| * @returns {Command[]} | |||
| */ | |||
|
|
|||
| /** | |||
There was a problem hiding this comment.
There is already an existing JSDoc for this routine. This should presumably be a modification rather than an addition. (This is true of many of the additions.)
|
I added a couple of comments to explain two of the issues I noticed. I think the suggestions would be welcome while I was actually adding new code or working on a routine. But not as a change-lots PR. In this project we have manually maintained dual documentation in the JavaScript files and the TypeScript interface definition files. I think there is too much work to take the generic suggested improvements in the JavaScript and fix up the problems, and reproduce the changes. |
|
Understood. Appreciate the feedback. This is a good use case to understand and make adjustments to OtterDoc. I think a lot of people feel the same way. |
This pull request offers concise yet comprehensive updates to function and class documentation.
This PR contains no functional changes, only documentation improvements.