feat: addd docstrings to scripts functions #4070
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`
akshatnema
requested review from
Mayaleeeee,
anshgoyalevil,
asyncapi-bot-eve,
derberg and
sambhavgupta0705
as code owners
WalkthroughThis change set comprehensively updates and expands JSDoc comments throughout a wide range of script files and utility modules. The documentation improvements clarify function behaviors, detail parameters and return values, and explicitly describe error handling across build scripts for posts, RSS feeds, case studies, adopters, finance, tools, and utility functions. No changes are made to the implementation logic, function signatures, or control flow in any file; all modifications are strictly confined to enhancing code documentation for clarity, completeness, and maintainability. Changes
Sequence Diagram(s)No sequence diagrams generated, as the changes are limited to documentation updates and do not affect control flow or introduce new features. Possibly related PRs
Suggested labels
Suggested reviewers
Poem
✨ Finishing Touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 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
|
✅ 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 @@
## master #4070 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 22 22
Lines 742 742
Branches 123 123
=========================================
Hits 742 742 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (1)
scripts/adopters/index.ts (1)
18-20:⚠️ Potential issueCritical: Missing
awaitonwriteJSON.
BecausewriteJSONreturns a Promise, omittingawaitmeansbuildAdoptersListmay resolve before the file is written, leading to race conditions.Apply this fix:
-export async function buildAdoptersList() { - writeJSON('config/adopters.yml', resolve(currentDirPath, '../../config', 'adopters.json')); +export async function buildAdoptersList() { + await writeJSON('config/adopters.yml', resolve(currentDirPath, '../../config', 'adopters.json')); }
🧹 Nitpick comments (19)
scripts/build-pages.ts (1)
40-47: Consider documenting return type.
SincecopyAndRenameFilesperforms file operations and does not return a value, adding an@returns {void}tag would improve clarity in the JSDoc.scripts/build-meetings.ts (1)
12-19: Add missing return annotation.
ThebuildMeetingsfunction isasyncand resolves with no value after writing the file. Consider adding an@returns {Promise<void>}tag to explicitly document this.scripts/markdown/check-edit-links.ts (1)
63-70: Consider documenting thrown errors incheckUrls.
Currently, the JSDoc forcheckUrlscovers parameters and return values but omits any@throwstag. Since a failure inprocessBatchwill reject the Promise and bubble up, it would be helpful to callers to know that this function may throw.Apply this diff to add an
@throwsannotation:* @returns A promise that resolves to an array of path objects with broken links. + * @throws {Error} If processing any batch fails.utils/redirect.ts (1)
6-15: Great enhancement of theuseRedirectJSDoc.
The comment now clearly states the hook’s behavior, including language detection, URL determination, and loop prevention.To tighten types, consider changing the return signature from
anyto a more accurate type, for example:-export function useRedirect(to: string | undefined): any { +export function useRedirect(to?: string): null {scripts/build-tools.ts (1)
13-26: Solid JSDoc forbuildTools.
The comment thoroughly covers GitHub data fetching, conversion, file writes, merging, and error semantics.You might also add a
@returnsannotation to indicate the function returns aPromise<void>:* @throws {Error} If an error occurs during the build process. + * @returns {Promise<void>} Resolves when the tools data has been successfully built and written.scripts/adopters/index.ts (1)
9-17: Docstring improvements are on point.
The description captures the YAML→JSON flow and file paths correctly.Consider enhancing with
@returnsand@throwstags:* @param readPath - The path of the YAML file to read. * @param writePath - The destination JSON file path. + * @returns {Promise<void>} Resolves when the JSON file has been written. + * @throws {Error} If reading, conversion, or writing fails.scripts/utils/readAndWriteJson.ts (1)
5-13: JSDoc forwriteJSONis informative.
It accurately describes reading, conversion, writing, and error cases.For completeness, consider adding a
@returnsannotation:* @throws {Error} If reading the file, converting its content to JSON, or writing fails. + * @returns {Promise<void>} Resolves when the JSON has been successfully written.scripts/tools/combine-tools.ts (1)
49-59: Add @async tag for asynchronous function.The JSDoc accurately describes the behavior of
getFinalTool, but since it returns a promise and is declared asasync, consider adding an@asyncannotation to the comment. This makes the asynchronous nature explicit for readers and tooling:/** * Enriches a tool object by processing its language and technology filters for display on the website. + * @async * @param toolObject - The original tool object containing filter tags. * @returns A promise that resolves to the updated tool object with enriched language and technology filters. */ export async function getFinalTool(toolObject: AsyncAPITool): Promise<FinalAsyncAPITool> {scripts/build-rss.ts (2)
7-11: Consider adding @async annotation.The JSDoc for
getAllPostscorrectly states that it returns a promise, but adding an@asynctag will make its asynchronous nature explicit:/** * Asynchronously retrieves all blog posts from the posts configuration file. + * @async * @returns A promise that resolves to the list of blog posts. */ async function getAllPosts() { ... }
41-55: Include @async annotation forrssFeed.The block documents parameters, return behavior, and errors well. Since
rssFeedis declaredasync, adding an@asynctag will improve clarity:/** * Generates and writes an RSS feed file for a specified blog post type. + * @async * @param type - The blog post type to include in the feed. * ... * @throws {Error} If any blog post is missing required fields or if an error occurs during the RSS feed generation or file writing process. */ export async function rssFeed(...) { ... }scripts/finance/index.ts (1)
18-27: Enhance JSDoc with @async and detailed param tags.To improve clarity and tooling support, consider:
- Adding an
@asyncannotation.- Expanding
@param propsinto individual@paramtags for each destructured property./** - * Builds the finance information list by converting YAML configuration files to JSON format. + * @async + * Builds the finance information list by converting YAML configuration files to JSON format. * - * @param props - An object containing configuration paths and the year used for locating the YAML files and determining the output directory. + * @param props.currentDir - The base directory path. + * @param props.configDir - Relative path to the config directory. + * @param props.financeDir - Subdirectory name for finance data. + * @param props.year - Year folder to process. + * @param props.jsonDataDir - Output directory for generated JSON files. * @returns A promise that resolves when the finance information list has been successfully built. * @throws {Error} If an error occurs during the conversion or file writing process. */ export async function buildFinanceInfoList(...) { ... }scripts/index.ts (1)
15-23: Add @async annotation tostartJSDoc.The
startfunction orchestrates asynchronous tasks. Including an@asynctag will make its async nature explicit:/** + * @async * Initiates the build process for the project's content. * * This asynchronous function orchestrates the creation of various content lists... * @throws {Error} If no numeric finance data is found in the finance directory. */ async function start() { ... }scripts/tools/extract-tools-github.ts (1)
12-20: Docstring clarifies behavior and error conditions
The updated JSDoc accurately describes search parameters, pagination, rate‐limit pause, return type, and thrown errors. Consider adding an@asynctag to explicitly denote that this function is asynchronous for tooling that parses JSDoc.scripts/tools/tools-object.ts (1)
28-41: Clear JSDoc forcreateToolObject
The docstring concisely explains parameter fallbacks and the constructed object. For consistency with other async utilities, you may add an@asynctag.scripts/markdown/check-markdown.ts (2)
133-142: Approve recursive file walker doc
The docstring thoroughly covers directory traversal, file filtering, validation invocation, and error conditions. For completeness, consider adding a@returns {Promise<void>}tag.
193-198: Approvemainorchestration doc
The comment accurately summarizes concurrent frontmatter validation and exit behavior. Adding@returns {Promise<void>}would align it with other async functions.scripts/dashboard/build-dashboard.ts (1)
226-234: Suggest adding@returnstag
The doc covers@paramand@throwsforwriteToFilebut omits a@returns {Promise<void>}. Including it would improve consistency.scripts/build-post-list.ts (2)
117-127: Clarify mutation and return behavior in spec-version handler
The docstring describes the branching logic well, but it doesn’t explicitly state that the inputdetailsobject is mutated in-place. Consider:
- Adding
@returns {Details}to indicate the return type.- Mentioning side-effects on the passed-in object.
152-171: Enhance async traversal doc with return type
Great coverage of parameters, recursion, and error cases forwalkDirectories. For completeness:
- Add a
@returns {Promise<void>}tag.- Note that
resultObjis mutated as a side effect.
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (21)
scripts/adopters/index.ts(1 hunks)scripts/build-docs.ts(2 hunks)scripts/build-meetings.ts(1 hunks)scripts/build-newsroom-videos.ts(1 hunks)scripts/build-pages.ts(2 hunks)scripts/build-post-list.ts(6 hunks)scripts/build-rss.ts(3 hunks)scripts/build-tools.ts(1 hunks)scripts/casestudies/index.ts(1 hunks)scripts/compose.ts(1 hunks)scripts/dashboard/build-dashboard.ts(9 hunks)scripts/finance/index.ts(1 hunks)scripts/index.ts(1 hunks)scripts/markdown/check-edit-links.ts(5 hunks)scripts/markdown/check-markdown.ts(4 hunks)scripts/tools/combine-tools.ts(1 hunks)scripts/tools/extract-tools-github.ts(1 hunks)scripts/tools/tools-object.ts(2 hunks)scripts/utils.ts(1 hunks)scripts/utils/readAndWriteJson.ts(1 hunks)utils/redirect.ts(1 hunks)
⏰ Context from checks skipped due to timeout of 180000ms (1)
- GitHub Check: Lighthouse CI
🔇 Additional comments (27)
scripts/utils.ts (1)
3-13: Well-documented conversion utility.
The JSDoc forconvertToJsonclearly outlines behavior, parameters, return type, and error conditions, matching the function logic precisely.scripts/build-pages.ts (1)
22-29: Comprehensive doc forcapitalizeJsxTags.
The updated comment accurately describes the regex-based capitalization behavior, parameter, and return value.scripts/compose.ts (1)
24-32: Clear and concise JSDoc forgenFrontMatter.
The docstring effectively explains the front matter structure, parameters, and return value, aligning with the implementation.scripts/build-newsroom-videos.ts (1)
14-21: Excellent JSDoc enhancement.
The docstring forbuildNewsroomVideosthoroughly details parameters, return type, and error conditions, matching the implementation without introducing inconsistencies.scripts/markdown/check-edit-links.ts (4)
22-34: Comprehensive JSDoc forprocessBatchlooks solid.
The added documentation accurately describes the HTTP HEAD request behavior, timeout handling, skip logic, return values, and error propagation.
99-106: JSDoc fordetermineEditLinkis clear and complete.
The description accurately covers path normalization, edit option matching, fallback logic, and null return cases. Parameter and return annotations are precise.
133-145: Excellent documentation forgeneratePaths.
The recursive traversal, skip logic, URL/path transformation, result accumulation, and error handling are all well-described.
190-197: Well-detailed JSDoc formain.
The overall workflow, configuration loading, path generation, URL checking, logging of invalid links, and error throwing are all clearly explained.scripts/build-rss.ts (1)
19-26: Documentation forcleanis clear and concise.The JSDoc thoroughly covers the purpose, behavior, and return value of the
cleanfunction, detailing all HTML entities handled. No changes needed here.scripts/casestudies/index.ts (1)
7-17: JSDoc forbuildCaseStudiesListis comprehensive and accurate.The comment clearly documents the function’s behavior, parameters, return value, and error conditions, aligning well with the implementation.
scripts/tools/tools-object.ts (1)
70-81: Comprehensive JSDoc forconvertTools
The updated comment accurately outlines filtering by filename, YAML-to-JSON conversion, schema validation, fuzzy category assignment, and error handling. Inclusion of an@throwstag is appropriate here.scripts/markdown/check-markdown.ts (2)
11-16: Approve URL validation doc
The JSDoc clearly describes the purpose, parameter, and return value ofisValidURL.
42-52: Approve frontmatter validation doc for blogs
The expanded doc details required fields and their format checks invalidateBlogs, enhancing clarity for future maintainers.scripts/build-docs.ts (2)
9-23: ApprovebuildNavTreeJSDoc
This JSDoc effectively explains tree initialization, item sorting, the “reference/specification” special case, and error conditions. All parameters and throws cases are documented.
163-174: ApproveaddDocButtonsJSDoc
The docstring clearly describes sequential document traversal, welcome page inclusion, and prev/next link logic, including parameter and return types.scripts/dashboard/build-dashboard.ts (8)
24-31: ApprovemonthsSinceJSDoc
Clear description of month calculation using a 30-day approximation, with correct@paramand@returns.
41-50: ApprovegetLabelJSDoc
The comment accurately explains label extraction logic, including edge cases where no match is found.
58-68: ApprovegetDiscussionsJSDoc
Excellent detail on recursive pagination, rate-limit warnings, pause logic, and return value.
110-119: ApprovegetDiscussionByIDJSDoc
Comprehensive description of conditional PR vs. issue fetching, return types, and error handling.
138-148: ApproveprocessHotDiscussionsJSDoc
Well‐detailed summary of comment pagination, interaction count computation (including PR reviews), and score normalization.
196-204: ApprovegetHotDiscussionsJSDoc
Clear documentation of batching, rate-limit pauses, sorting, bot filtering, and result sizing.
254-259: ApprovemapGoodFirstIssuesJSDoc
The documentation precisely explains transformation logic, filtered labels, and return structure.
280-289: Approvestartorchestration JSDoc
Comprehensive summary of dashboard data fetching, processing, concurrent operations, and error logging, with correct@paramand@returns.scripts/build-post-list.ts (4)
29-38: Slug extractor docstring provides clear intent
The JSDoc forslugifyToCaccurately describes its purpose, parameters, and return values. It clearly outlines the matching regex, input validation, and fallback behavior.
53-60: Capitalization helper documentation is concise and precise
The docstring forcapitalizesuccinctly explains the transformation logic and covers the splitting/joining behavior. It’s clear and complete.
94-106: Version details parser docstring is well-structured
The JSDoc forgetVersionDetailsthoroughly documents how the version is parsed, normalized, and returned with weight. Parameters and return fields are clearly defined.
278-292: Post list builder docstring is comprehensive
The JSDoc forbuildPostListclearly outlines validation, processing steps, error handling,@param,@returns, and@throws. No changes needed.
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.tsDescription
Related issue(s)
Summary by CodeRabbit