feat: add docstrings in scripts files #3770
Conversation
Docstrings generation was requested by @akshatnema. * #3761 (comment) The following files were modified: * `scripts/adopters/index.ts` * `scripts/build-docs.ts` * `scripts/build-meetings.ts` * `scripts/build-newsroom-videos.ts` * `scripts/build-pages.ts` * `scripts/build-post-list.ts` * `scripts/build-rss.ts` * `scripts/build-tools.ts` * `scripts/casestudies/index.ts` * `scripts/compose.ts` * `scripts/dashboard/build-dashboard.ts` * `scripts/finance/index.ts` * `scripts/index.ts` * `scripts/markdown/check-edit-links.ts` * `scripts/markdown/check-markdown.ts` * `scripts/tools/combine-tools.ts` * `scripts/tools/extract-tools-github.ts` * `scripts/tools/tools-object.ts` * `scripts/utils.ts` * `scripts/utils/readAndWriteJson.ts` * `utils/redirect.ts`
coderabbitai
bot
requested review from
Mayaleeeee,
akshatnema,
anshgoyalevil,
asyncapi-bot-eve and
derberg
as code owners
WalkthroughThis pull request updates documentation comments throughout multiple scripts. The changes clarify function behavior, parameter descriptions, return types, and error handling for processes including file conversion, content building, API data retrieval, and markdown validation. A few function signatures have been adjusted to specify explicit return types. No underlying functionality or control flow has been modified. Changes
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
📜 Recent review detailsConfiguration used: .coderabbit.yaml 📒 Files selected for processing (21)
🔇 Additional comments (47)
✨ Finishing Touches
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
✅ Deploy Preview for asyncapi-website ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## migrate-scripts #3770 +/- ##
=================================================
Coverage 100.00% 100.00%
=================================================
Files 21 21
Lines 667 667
Branches 113 113
=================================================
Hits 667 667 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
akshatnema
changed the title
migrate-scripts
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
|
@akshatnema LGTM! |
|
/rtm |
| * @param writePath - The file path where the video data will be saved. | ||
| * @returns A promise that resolves to a JSON string containing the video data. | ||
| * | ||
| * @throws Error if the YOUTUBE_TOKEN environment variable is not set, if the API request fails, or if the response has an unexpected structure. |
There was a problem hiding this comment.
Add @throws {Error} for consistency.
Ideally, we shouldn't mention {Error} in any of the JSDoc comments as we are using TypeScript. In TypeScript, the type system already knows you're likely throwing an Error. But it may be useful for clarity/documentation purposes. We need to discuss this and decide on a standard practice.
| * contain a valid heading ID, an empty string is returned. | ||
| * | ||
| * @param str - The input markdown string that may contain a heading ID. | ||
| * @returns The extracted slug used for table of contents, or an empty string if no valid ID is found. |
There was a problem hiding this comment.
Should add the return type here as it is not explicitly mentioned in the function definition.
More better way will be to define the return type in the function definition itself, and the JSDoc comment (@return) will itself be able to describe what is being returned.
| * @param {string} text - The string to capitalize. | ||
| * @returns {string} - The capitalized string. | ||
| * @param text - The string to transform. | ||
| * @returns The transformed string with each word's initial letter capitalized. |
There was a problem hiding this comment.
Should add the return type here as it is not explicitly mentioned in the function definition.
More better way will be to define the return type in the function definition itself, and the JSDoc comment (@return) will itself be able to describe what is being returned.
There was a problem hiding this comment.
I have reviewed all the comments. The descriptions provided are more detailed than necessary. While they clearly explain what the functions are doing, they are excessively long.
Additionally, there are inconsistencies in typing, particularly with @throw and @return.
-
Ideally, we should not mention {Error} after @throw in JSDoc comments, since we are using TypeScript and the type system already infers that an Error is being thrown. However, if needed for clarity, we can discuss and establish a standard practice.
-
In many functions, the return type is not explicitly specified in the function definition. Preferably, we should add the return type in the function signature rather than rely on JSDoc, especially since this PR aims to clean up JSDoc comments.
4 participants
Docstrings generation was requested by @akshatnema.
The following files were modified:
scripts/adopters/index.tsscripts/build-docs.tsscripts/build-meetings.tsscripts/build-newsroom-videos.tsscripts/build-pages.tsscripts/build-post-list.tsscripts/build-rss.tsscripts/build-tools.tsscripts/casestudies/index.tsscripts/compose.tsscripts/dashboard/build-dashboard.tsscripts/finance/index.tsscripts/index.tsscripts/markdown/check-edit-links.tsscripts/markdown/check-markdown.tsscripts/tools/combine-tools.tsscripts/tools/extract-tools-github.tsscripts/tools/tools-object.tsscripts/utils.tsscripts/utils/readAndWriteJson.tsutils/redirect.tsThese files were ignored
tests/adopters/index.test.jstests/build-docs/addDocButtons.test.jstests/build-docs/buildNavTree.test.jstests/build-docs/convertDocPosts.test.jstests/build-meetings.test.jstests/build-newsroom-videos.test.jstests/build-pages.test.jstests/build-post-list.test.jstests/build-rss.test.jstests/build-tools.test.jstests/casestudies/index.test.jstests/dashboard/build-dashboard.test.jstests/finance/index.test.jstests/index.test.jstests/markdown/check-edit-links.test.jstests/markdown/check-markdown.test.jstests/readAndWriteJson.test.jstests/tools/combine-tools.test.jstests/tools/extract-tools-github.test.jstests/tools/tools-object.test.jstests/utils.test.jsThese file types are not supported
package.jsonscripts/tools/tools-schema.jsontsconfig.jsonℹ️ Note
Summary by CodeRabbit