feat: add docstrings in scripts files

[coderabbitai]

Docstrings generation was requested by @akshatnema.

• feat: migrate script to typescript (#3423) #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

These files were ignored

• tests/adopters/index.test.js
• tests/build-docs/addDocButtons.test.js
• tests/build-docs/buildNavTree.test.js
• tests/build-docs/convertDocPosts.test.js
• tests/build-meetings.test.js
• tests/build-newsroom-videos.test.js
• tests/build-pages.test.js
• tests/build-post-list.test.js
• tests/build-rss.test.js
• tests/build-tools.test.js
• tests/casestudies/index.test.js
• tests/dashboard/build-dashboard.test.js
• tests/finance/index.test.js
• tests/index.test.js
• tests/markdown/check-edit-links.test.js
• tests/markdown/check-markdown.test.js
• tests/readAndWriteJson.test.js
• tests/tools/combine-tools.test.js
• tests/tools/extract-tools-github.test.js
• tests/tools/tools-object.test.js
• tests/utils.test.js

These file types are not supported

• package.json
• scripts/tools/tools-schema.json
• tsconfig.json

ℹ️ Note

CodeRabbit cannot perform edits on its own pull requests yet.

Summary by CodeRabbit

• Documentation
  • Enhanced internal documentation across various content processing and build routines. These improvements clarify data handling, error management, and configuration details, which will support ongoing maintenance. No visible changes to functionality or user experience were made.

[coderabbitai]

Walkthrough

This 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

File(s)	Summary of Changes
scripts/adopters/index.ts, scripts/build-docs.ts, scripts/build-meetings.ts, scripts/build-newsroom-videos.ts, scripts/build-pages.ts	Enhanced and clarified JSDoc comments to more precisely describe function operations, parameters, and error handling without changing functionality.
scripts/build-post-list.ts	Updated documentation and function signatures with explicit return types for functions involved in constructing post lists.
scripts/build-rss.ts	Expanded documentation for post retrieval, HTML cleaning, and RSS feed generation, with refined error handling details.
scripts/build-tools.ts, scripts/casestudies/index.ts, scripts/compose.ts	Improved documentation comments to elaborate on content processing and file writing operations.
scripts/dashboard/build-dashboard.ts	Extensively refined documentation for multiple functions managing dashboard data processing, argument handling, and file output.
scripts/finance/index.ts, scripts/index.ts	Revised docs for functions handling finance information and overall content build orchestration with clearer descriptions and error management.
scripts/markdown/check-edit-links.ts, scripts/markdown/check-markdown.ts	Detailed enhancements to documentation for markdown link checking and validation, outlining workflows and error handling strategies.
scripts/tools/combine-tools.ts, scripts/tools/extract-tools-github.ts, scripts/tools/tools-object.ts	Clarified documentation on tool data processing, GitHub API integration, and tag enrichment workflows.
scripts/utils.ts, scripts/utils/readAndWriteJson.ts, utils/redirect.ts	Updated utility function documentation to better explain JSON conversion, file I/O operations, and redirection logic.

Possibly related PRs

• feat: added test for build-rss.js #3101: Focuses on documentation improvements for the rssFeed function in scripts/build-rss.ts, sharing a direct code-level connection with the changes in this PR.

Suggested labels

ready-to-merge, autoupdate

Suggested reviewers

• derberg
• magicmatatjahu
• anshgoyalevil
• Mayaleeeee
• asyncapi-bot-eve
• devilkiller-ag
• sambhavgupta0705

Poem

Oh, what a hop this update brings,
As docs now sing with clearer strings.
I’m a rabbit, delighted to see
Each comment now shines brightly and free.
With every tweak, our code’s set right—
Bouncing boldly into a future so bright!
🐰💫 Enjoy the leaps of clarity!

---

📜 Recent review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c06d2af and f49eee6.

📒 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)

🔇 Additional comments (47)

scripts/adopters/index.ts (1)

9-16: Well-documented function with comprehensive details.

The updated docstring provides excellent clarity about the function's purpose, the specific files it works with, and the resolution logic for file paths. This is a significant improvement that makes the codebase more maintainable.

scripts/finance/index.ts (1)

18-26: Clear and thorough documentation with excellent error handling context.

The updated docstring now properly explains the YAML to JSON conversion process, details the specific files being processed, and documents the error handling behavior. Including the @throws annotation is particularly helpful for users of this function.

utils/redirect.ts (1)

7-13: Improved clarity and technical accuracy in documentation.

The revised documentation clearly explains the language detection process and prevention of infinite redirection loops. This gives developers a much better understanding of how this hook functions internally and what edge cases it handles.

scripts/tools/combine-tools.ts (1)

50-58: Excellent technical documentation with implementation details.

The updated docstring provides a clear explanation of the fuzzy matching process, how new tags are handled, and the structure of the returned object. This level of detail makes the code much more maintainable and helps future developers understand the purpose of this function.

scripts/utils.ts (1)

4-12: Well-documented function with comprehensive details!

The updated docstring for convertToJson now provides clear information about the function's behavior, parameters, return values, and error handling. It effectively explains the logic flow: treating non-string inputs as JSON objects, attempting JSON parsing first, then YAML parsing as a fallback.

scripts/utils/readAndWriteJson.ts (1)

6-12: Clear and informative documentation improvement!

The enhanced docstring for writeJSON now thoroughly explains the function's purpose, processing flow, and error handling. The parameter descriptions are concise yet informative, and the error documentation clearly indicates when exceptions might be thrown.

scripts/tools/extract-tools-github.ts (1)

13-19: Excellent documentation with specific implementation details!

The revised docstring for getData now provides detailed information about:

• The specific search criteria (".asyncapi-tool" files)
• Pagination behavior (50 items per page)
• Rate limiting considerations (1-second pause between requests)
• Clear return type expectations
• Comprehensive error handling documentation

This level of detail helps developers understand both the function's purpose and its implementation constraints.

scripts/index.ts (1)

15-22: Comprehensive documentation of the orchestration function!

The updated docstring for start now clearly explains its role as the orchestrator for building various content types. The documentation effectively describes:

• The function's overall purpose
• The specific content types being processed
• The finance data handling logic with year filtering
• The specific error condition that could be thrown

This documentation provides excellent context for understanding this key function's responsibilities.

scripts/compose.ts (1)

24-32: Great improvement to the function documentation!

The enhanced docstring now provides a clear, comprehensive explanation of the function's purpose and behavior. It effectively explains not only what the function does (generates front matter) but also details the components included in the output, making the documentation more complete.

The parameter and return descriptions are also more user-friendly and informative.

scripts/build-docs.ts (2)

9-23: Well-documented function with clear implementation details!

The revised documentation thoroughly explains the navigation tree construction process, including initialization with a "Welcome" section, how items are sorted and organized, and the error handling approach. The explanation about updating the href for the "specification" subgroup is particularly helpful for understanding the special case handling.

The @throws tag properly documents the error conditions, which is important for users of this function.

---

163-173: Excellent clarification of the document navigation enhancement process!

The updated documentation clearly explains how the navigation functionality works, including important details about including the welcome page as the first post and excluding non-content section markers. This provides valuable context for developers working with these document navigation structures.

scripts/build-newsroom-videos.ts (1)

14-21: Comprehensive function documentation with improved error handling details!

The docstring improvements make the function's purpose and behavior significantly clearer. I especially appreciate the expanded error handling documentation that now specifically mentions the three potential error conditions:

1. Missing YOUTUBE_TOKEN environment variable
2. API request failures
3. Unexpected response structure

This level of detail helps users understand exactly what might go wrong and how to diagnose issues.

scripts/build-tools.ts (1)

14-26: Much clearer documentation of the tools data processing workflow!

The enhanced documentation provides a complete picture of the function's workflow, from data retrieval to conversion, combination, and output. The parameter descriptions are now more focused on their purpose rather than their types (which are already visible in the function signature).

This improved clarity makes the code more maintainable and easier for new developers to understand.

scripts/build-meetings.ts (1)

11-19: Well-structured and comprehensive documentation.

The updated docstring provides detailed information about the function's behavior, including the specific time window for fetching calendar events and authentication process. The parameter description is clear, and the error handling conditions are well specified.

scripts/build-pages.ts (2)

22-29: Clear and improved function description.

The updated documentation clearly explains the purpose of capitalizing JSX tag names in a predefined list and the process by which this is accomplished. The parameter and return value descriptions are concise and informative.

---

41-47: Comprehensive explanation of file processing.

The expanded documentation provides excellent detail about the recursive file copying process, including the content transformations applied. The separation of file and directory handling is well documented, and the parameter descriptions are clear.

scripts/casestudies/index.ts (1)

7-17: Enhanced documentation with error handling details.

The updated documentation clearly explains the function's purpose, process flow, and error handling. The addition of the @throws section is particularly valuable as it explicitly documents the error conditions that callers should handle.

scripts/tools/tools-object.ts (2)

29-41: Detailed explanation of tool object construction.

The updated documentation effectively describes the process of building a tool object for frontend display. The explanation of fallback values for missing fields is particularly helpful for understanding the function's behavior.

---

71-81: Comprehensive documentation of tools processing workflow.

The expanded documentation clearly explains the categorization process for tools, including the validation against a JSON schema and fuzzy search for categories. The error handling section is a valuable addition that helps users understand potential failure modes.

scripts/markdown/check-markdown.ts (4)

11-16: Good use of JSDoc comments for the isValidURL function.

The updated documentation clearly explains the function's purpose, parameters, and return value in a concise manner.

---

42-51: Excellent comprehensive documentation for the validateBlogs function.

The updated comment provides a detailed explanation of the validation process and checks performed on different fields. This significantly improves code maintainability by clearly documenting the function's behavior and expectations.

---

134-142: Well-structured documentation for checkMarkdownFiles.

The comment effectively explains the recursive traversal process, file filtering, and error handling. The @throws tag is particularly helpful for understanding potential failure points.

---

193-197: Clear and concise documentation for the main function.

The comment succinctly explains the function's purpose and execution flow, which is helpful for understanding the entry point of this module.

scripts/build-rss.ts (3)

8-10: Improved clarity in the getAllPosts function documentation.

The addition of "asynchronously" helps clarify the function's behavior and accurately reflects its Promise-returning nature.

---

19-25: Detailed documentation for the clean function.

The updated comment precisely describes which HTML entities are replaced and what the function does with "&ltspan&gt". This level of detail is very helpful for maintainers.

---

41-54: Thorough documentation for the rssFeed function.

The expanded comment provides excellent detail about the function's process flow, from retrieving posts to generating the RSS feed. The @throws tag clearly documents error conditions, which is valuable for error handling.

scripts/markdown/check-edit-links.ts (5)

23-33: Comprehensive documentation for the processBatch function.

The comment clearly explains the HTTP request process, timeout handling, and the conditions under which files are skipped. The inclusion of information about the configurable timeout is particularly helpful.

---

64-69: Informative documentation for the checkUrls function.

The comment effectively explains the batching process and environment variable usage, which helps developers understand configuration options available.

---

100-110: Detailed explanation of the determineEditLink function.

The documentation clearly describes the logic for generating edit links, including the special handling for different cases. This helps maintainers understand the link generation process.

---

133-144: Thorough documentation for the generatePaths function.

The comment provides a clear explanation of the recursive file processing, URL path construction, and the structure of the returned objects. The explicit mention of skipping certain files is helpful for understanding the filtering logic.

---

190-196: Well-structured documentation for the main function.

The comment effectively describes the workflow for validating edit links, from loading configurations to logging results. The error handling documentation is particularly valuable.

scripts/build-post-list.ts (7)

30-37: Clear documentation for the slugifyToC function.

The comment effectively explains the function's purpose, edge cases, and return value expectations. The explanation of when an empty string is returned is particularly helpful.

---

54-59: Concise documentation for the capitalize function.

The comment clearly describes the transformation process and expected output, which helps developers understand this utility function's behavior.

---

95-106: Informative documentation for the getVersionDetails function.

The comment effectively explains how version information is extracted and processed from slugs, including the special handling of the "v" prefix.

---

118-126: Detailed documentation for the handleSpecificationVersion function.

The comment clearly describes the conditions under which titles are modified and flags are set, which helps maintain the logic around versioning.

---

143-146: Concise documentation for the isDirectory function.

While simple, the comment accurately describes the function's purpose and return type.

---

153-171: Excellent comprehensive documentation for the walkDirectories function.

The comment thoroughly explains the complex recursive traversal process, special file handling, and data extraction. The detailed parameter descriptions are particularly valuable for understanding this complex function.

---

279-291: Well-structured documentation for the buildPostList function.

The comment effectively describes the validation process, directory processing, and error handling. The inclusion of the @throws tag with specific error conditions is particularly helpful.

scripts/dashboard/build-dashboard.ts (9)

24-31: Well-documented function!

The added docstring clearly explains the function's purpose, method of calculation, and the 30-day month approximation used. The parameter and return type documentation is thorough.

---

40-50: Great documentation for label processing logic

The docstring effectively describes how this function extracts label information, including its search method and result format. The parameter and return type documentation is clear and precise.

---

57-68: Excellent API interaction documentation

This docstring thoroughly explains the recursive pagination logic, rate limit handling, and API interaction details. The documentation of parameters and return values is comprehensive and helpful for future maintainers.

---

109-119: Clear and complete function documentation

The docstring properly describes the function's purpose with appropriate distinction between PR and issue retrieval. Good inclusion of the @throws tag to document error handling behavior.

---

137-148: Thorough batch processing documentation

The docstring clearly explains the complex logic for processing discussions, including score calculation based on interaction counts and time normalization. The error handling documentation is helpful.

---

195-204: Well-documented batch processing function

The docstring effectively explains the batching strategy, rate limit management through pauses, and the filtering/sorting logic that produces the final result set.

---

225-234: Clear file writing documentation

The docstring properly describes the data serialization process and includes appropriate error handling documentation. The parameter descriptions are precise and helpful.

---

253-262: Good transformation documentation

The docstring effectively describes how issues are mapped to a simplified format, including details on default values and filtering logic for the labels.

---

279-289: Excellent orchestration function documentation

This docstring provides a comprehensive overview of the entire dashboard generation process, clearly explaining the data flow from retrieval through processing to storage. The error handling documentation is appropriate.

✨ Finishing Touches

• 📝 Generate Docstrings

---

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?

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

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)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[github-actions]

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.

[netlify]

✅ Deploy Preview for asyncapi-website ready!

Name	Link
🔨 Latest commit	f49eee6
🔍 Latest deploy log	https://app.netlify.com/sites/asyncapi-website/deploys/67c380a3d028c2000841720a
😎 Deploy Preview	https://deploy-preview-3770--asyncapi-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (c06d2af) to head (f49eee6).

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.
📢 Have feedback on the report? Share it here.

[akshatnema]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.