feat: addd docstrings to scripts functions

scripts/adopters/index.ts

@@ -7,7 +7,13 @@ const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
 
 /**
- * Builds the adopters list by converting a YAML file to JSON and writing it to a specified path.
+ * Converts the YAML adopters configuration to a JSON file.
+ *
+ * This asynchronous function reads the adopters configuration from
+ * "config/adopters.yml" and converts its content to JSON format. It then writes
+ * the resulting JSON data to "adopters.json" in the configuration directory determined
+ * by resolving the current file's directory with "../../config". The operation is
+ * performed using the writeJSON utility.
  */
 export async function buildAdoptersList() {
   writeJSON('config/adopters.yml', resolve(currentDirPath, '../../config', 'adopters.json'));

scripts/build-docs.ts

@@ -6,11 +6,20 @@ import type { Details, NavigationPage } from '@/types/scripts/build-posts-list';
 const { sortBy } = lodash;
 
 /**
- * Builds a navigation tree from the given navigation items.
+ * Constructs a navigation tree from an array of navigation items.
  *
- * @param {Details[]} navItems - The navigation items to build the tree from.
- * @returns {NavTree} - The built navigation tree.
- * @throws {Error} - Throws an error if there is an issue during the tree building process.
+ * The tree is initialized with a default "Welcome" section and then populated by sorting
+ * and organizing items into root sections, subsections, and documents. Each item is placed under its
+ * appropriate parent, and an error is thrown if a referenced parent section is not found.
+ *
+ * For the root section identified as "reference", if a "specification" subgroup exists,
+ * its href is updated to point to the latest stable specification version.
+ *
+ * @param navItems - An array of navigation items with properties such as title, weight, section identifiers,
+ *                   and parent references.
+ * @returns The constructed navigation tree.
+ *
+ * @throws {Error} If a referenced parent section is missing or if any error occurs during the tree building process.
  */
 function buildNavTree(navItems: Details[]): NavTree {
   try {
@@ -151,12 +160,17 @@ const convertDocPosts = (docObject: NavTree | Details): Details[] => {
 };
 
 /**
- * Adds navigation buttons to the document posts.
+ * Enhances document posts by appending next and previous navigation data based on the navigation tree.
+ *
+ * This function traverses the navigation tree to create a sequential list of document posts and then adds
+ * navigation properties (`nextPage` and `prevPage`) to each page entry where applicable. It ensures that the
+ * welcome page (identified by the '/docs' slug) is included as the first post while excluding non-content
+ * section markers from navigation linking.
  *
- * @param {Details[]} docPosts - The document posts to add buttons to.
- * @param {NavTree} treePosts - The navigation tree of the document posts.
- * @returns {Details[]} - The document posts with added navigation buttons.
- * @throws {Error} - Throws an error if there is an issue during the button adding process.
+ * @param docPosts - The document posts to be augmented.
+ * @param treePosts - The hierarchical navigation tree that organizes the document posts.
+ * @returns The document posts enriched with navigation buttons for adjacent pages.
+ * @throws {Error} Throws an error if an issue occurs while adding navigation buttons.
  */
 function addDocButtons(docPosts: Details[], treePosts: NavTree): Details[] {
   let structuredPosts: Details[] = [];

scripts/build-meetings.ts

@@ -9,10 +9,13 @@ const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
 
 /**
- * Fetches upcoming meetings from Google Calendar and writes the data to a specified path.
+ * Fetches meeting events from Google Calendar within a predefined time window and writes the formatted data to a file.
  *
- * @param {string} writePath - The path to write the meeting data.
- * @throws {Error} - Throws an error if there is an issue during the fetch or write process.
+ * This function authenticates using service account credentials from environment variables and retrieves events from a calendar identified by an environment variable. It computes a time span ranging from 100 days before the current time to 30 days after, then processes each event to extract key details such as the title, calendar link, optional URL and banner, and the event date. If the API response is invalid or an event lacks a start date-time, an error is thrown. The formatted, pretty-printed JSON data is logged and written to the specified file path.
+ *
+ * @param writePath - The file system path where the output JSON data should be saved.
+ *
+ * @throws {Error} When authentication fails, the calendar API returns an invalid structure, or required event details are missing.
  */
 async function buildMeetings(writePath: string) {
   let auth;

scripts/build-newsroom-videos.ts

@@ -11,11 +11,14 @@ const currentFilePath = fileURLToPath(import.meta.url);
 const currentDirPath = dirname(currentFilePath);
 
 /**
- * Fetches the latest YouTube videos from the AsyncAPI channel and writes the data to a specified path.
+ * Retrieves the latest videos from the AsyncAPI YouTube channel and writes them as a formatted JSON string to the specified file.
  *
- * @param {string} writePath - The path to write the video data.
- * @returns {Promise<string>} - A promise that resolves to the video data in JSON format.
- * @throws {Error} - Throws an error if there is an issue during the fetch or write process.
+ * This function fetches video data from the YouTube API using the YOUTUBE_TOKEN environment variable. It extracts key details—including the thumbnail URL, title, description, and video ID—from the API response, writes the JSON-formatted data to the provided file path, and returns the JSON string.
+ *
+ * @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.
  */
 async function buildNewsroomVideos(writePath: string): Promise<string> {
   try {

scripts/build-pages.ts

@@ -19,10 +19,13 @@ export function ensureDirectoryExists(directory: PathLike) {
 ensureDirectoryExists(TARGET_DIR);
 
 /**
- * Capitalizes JSX tags in the provided content string.
+ * Capitalizes the first letter of JSX tag names in the provided content if they are in a predefined list.
  *
- * @param {string} content - The content string to process.
- * @returns {string} - The content string with capitalized JSX tags.
+ * This function scans the input string for opening and closing JSX tags using a regular expression.
+ * If a tag's lowercase name is found in the configured list of tags to capitalize, its first character is converted to uppercase.
+ *
+ * @param content - The string containing JSX elements.
+ * @returns The updated content with designated JSX tag names capitalized.
  */
 export function capitalizeJsxTags(content: string): string {
   return content.replace(/<\/?(\w+)/g, function (match: string, letter: string): string {
@@ -35,10 +38,12 @@ export function capitalizeJsxTags(content: string): string {
 }
 
 /**
- * Copies and renames files from the source directory to the target directory.
+ * Recursively copies files and directories from the source to the target directory with content transformations.
+ *
+ * The function processes each entry found in the source directory. For files, it transforms the content by converting HTML comments into JSX comments and capitalizing specific JSX tags. After transformation, the content is written to the target directory. Files with a '.md' extension are renamed to use the '.mdx' extension. For directories, a corresponding directory is created in the target if it doesn't exist, and the function is called recursively.
  *
- * @param {string} srcDir - The source directory.
- * @param {string} targetDir - The target directory.
+ * @param srcDir - The path to the source directory containing files and subdirectories.
+ * @param targetDir - The path to the target directory where transformed files and directories are written.
  */
 export function copyAndRenameFiles(srcDir: string, targetDir: string) {
   // Read all files and directories from source directory

scripts/build-post-list.ts

@@ -27,10 +27,14 @@ const releaseNotes: (string | undefined)[] = [];
 const HEADING_ID_REGEX = /[\s]*(?:\{#([a-zA-Z0-9\-_]+)\}|<a[\s]+name="([a-zA-Z0-9\-_]+)")/;
 
 /**
- * Slugifies a string for use in a table of contents.
+ * Extracts a slug from a markdown heading string for table of contents usage.
  *
- * @param {string} str - The string to slugify.
- * @returns {string} - The slugified string.
+ * This function searches for a valid heading ID in the form `{#someId}` within the input string
+ * and returns the trimmed ID as the slug. If the input is not a string, is empty, or does not
+ * 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.
  */
 export function slugifyToC(str: string) {
   if (typeof str !== 'string') return '';
@@ -47,10 +51,12 @@ export function slugifyToC(str: string) {
 }
 
 /**
- * Capitalizes the first letter of each word in a string.
+ * Capitalizes the first letter of each word in the provided string.
+ *
+ * This function splits the text on whitespace and hyphen characters, capitalizes the first letter of each segment, and then joins them with a space.
  *
- * @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.
  */
 function capitalize(text: string) {
   return text
@@ -86,11 +92,17 @@ export const addItem = (details: Details) => {
 };
 
 /**
- * Gets version details based on the slug and weight.
+ * Extracts version information from a slug and associates it with a weight.
  *
- * @param {string} slug - The slug of the item.
- * @param {number} weight - The weight of the item.
- * @returns {object} - The version details.
+ * This function parses the provided slug to obtain its basename and extracts the first segment (delimited by a hyphen) as the version identifier.
+ * If the identifier begins with a "v", that prefix is removed prior to capitalization.
+ * The resulting version title, along with the original weight, is returned in an object.
+ *
+ * @param slug - A string representing the slug from which the version is derived.
+ * @param weight - A numerical value representing the version's weight.
+ * @returns An object containing:
+ *   - title: The formatted version title.
+ *   - weight: The provided weight.
  */
 function getVersionDetails(slug: string, weight: number) {
   const fileBaseName = basename(slug);
@@ -103,11 +115,15 @@ function getVersionDetails(slug: string, weight: number) {
 }
 
 /**
- * Handles specification version details.
+ * Updates a details object by appending version indicators to its title and marking it as a pre-release when applicable.
+ *
+ * Specifically, if the file base name contains "next-spec" or "next-major-spec", the function sets the pre-release flag
+ * and appends " (Pre-release)" to the title. Additionally, if the file base name includes "explorer", it appends " - Explorer"
+ * to the title.
  *
- * @param {Details} details - The details of the item.
- * @param {string} fileBaseName - The base name of the file.
- * @returns {Details} - The updated details.
+ * @param details - The documentation item's details object.
+ * @param fileBaseName - The base name of the file, used to determine version markers.
+ * @returns The updated details object with modified title and version flags.
  */
 function handleSpecificationVersion(details: Details, fileBaseName: string) {
   const detailsObj = details;
@@ -124,25 +140,34 @@ function handleSpecificationVersion(details: Details, fileBaseName: string) {
 }
 
 /**
- * Checks if the given path is a directory.
+ * Determines whether the provided path refers to a directory.
  *
- * @param {PathLike} dir - The path to check.
- * @returns {Promise<boolean>} - A promise that resolves to true if the path is a directory, false otherwise.
+ * @param dir - The file system path to check.
+ * @returns A promise that resolves to true if the path is a directory, or false otherwise.
  */
 async function isDirectory(dir: PathLike) {
   return (await stat(dir)).isDirectory();
 }
 
 /**
- * Walks through directories and processes files.
+ * Recursively traverses an array of directory tuples to process markdown files and subdirectories,
+ * extracting metadata and building a hierarchical result structure.
  *
- * @param {string[][]} directories - The directories to walk through.
- * @param {Result} resultObj - The result object to store the processed data.
- * @param {string} basePath - The base path for the directories.
- * @param {string} [sectionTitle] - The title of the section.
- * @param {string} [sectionId] - The ID of the section.
- * @param {string} [rootSectionId] - The root ID of the section.
- * @param {number} [sectionWeight=0] - The weight of the section.
+ * For each directory tuple, where the first element is the directory path and the second an optional
+ * section slug, the function reads contained files. Subdirectories with a '_section.mdx' file have their
+ * metadata extracted to form section details, while markdown files (ending in .mdx but not with '_section.mdx')
+ * are parsed for front matter, table of contents, reading time, and excerpt information. Special processing
+ * applies for specification and release note files.
+ *
+ * @param directories - An array of directory tuples, each containing a directory path and an optional section slug.
+ * @param resultObj - The object to accumulate processed documentation, blog posts, and section details.
+ * @param basePath - The base path for resolving relative file paths in the project.
+ * @param sectionTitle - The title of the current section, used to annotate content files.
+ * @param sectionId - The identifier for the current section in a nested hierarchy.
+ * @param rootSectionId - The identifier for the root section in the hierarchy.
+ * @param sectionWeight - A numeric weight for ordering the section; defaults to 0.
+ *
+ * @throws {Error} When a file system operation or directory traversal fails.
  */
 async function walkDirectories(
   directories: string[][],
@@ -251,13 +276,19 @@ async function walkDirectories(
 }
 // Builds a list of posts from the specified directories and writes it to a file
 /**
- * Builds a list of posts from the specified directories and writes it to a file.
+ * Asynchronously builds a structured post list from nested directories and writes the resulting JSON to a file.
+ *
+ * The function validates that the base directory, write file path, and post directories are provided. It then
+ * normalizes the base path, recursively processes the provided directories to extract Markdown metadata, constructs
+ * a navigation tree from documentation posts, augments these posts with additional controls, and finally writes the
+ * complete result as a formatted JSON string to the specified file.
+ *
+ * @param postDirectories - A nested array of directories to search for posts.
+ * @param basePath - The base directory path used to resolve file locations.
+ * @param writeFilePath - The file path where the final JSON output will be written.
+ * @returns A promise that resolves when the post list has been successfully built and written.
  *
- * @param {string[][]} postDirectories - The directories containing the posts.
- * @param {string} basePath - The base path for the directories.
- * @param {string} writeFilePath - The path to write the resulting post list.
- * @returns {Promise<void>} - A promise that resolves when the post list is built and written.
- * @throws {Error} - Throws an error if there is an issue during the build process.
+ * @throws {Error} When required inputs are missing or an error occurs during directory traversal or file writing.
  */
 export async function buildPostList(
   postDirectories: string[][],

scripts/build-rss.ts

@@ -5,9 +5,9 @@ import type { Details, Result } from '@/types/scripts/build-posts-list';
 import type { BlogPostTypes, RSS, RSSItemType } from '@/types/scripts/build-rss';
 
 /**
- * Retrieves all blog posts from the configuration file.
+ * Asynchronously retrieves all blog posts from the posts configuration file.
  *
- * @returns {Promise<any>} - A promise that resolves to the list of all blog posts.
+ * @returns A promise that resolves to the list of blog posts.
  */
 async function getAllPosts() {
   const posts = (await import('../config/posts.json')).default as Result;
@@ -16,10 +16,13 @@ async function getAllPosts() {
 }
 
 /**
- * Cleans a string by replacing HTML entities with their corresponding characters.
+ * Cleans a string by replacing common HTML entities with their corresponding literal characters.
  *
- * @param {string} s - The string to clean.
- * @returns {string} - The cleaned string.
+ * This function converts HTML entities such as "&amp;", "&#39;", "&lt;", "&gt;", and "&quot;" into
+ * their respective characters and removes any occurrences of "&ltspan&gt".
+ *
+ * @param s - The string containing HTML entities to clean.
+ * @returns The string with HTML entities replaced by their literal characters.
  */
 function clean(s: string) {
   let cleanS = s;
@@ -35,13 +38,20 @@ function clean(s: string) {
 }
 
 /**
- * Generates an RSS feed for the specified blog post type.
+ * Generates and writes an RSS feed file for a specified blog post type.
+ *
+ * Retrieves all blog posts, filters out those without a publication date, and validates that each post
+ * contains the required fields (title, slug, excerpt, date). The posts are then sorted by featured status
+ * and publication date before being converted into an RSS feed structure. The resulting XML feed is written
+ * to the specified output file path.
+ *
+ * @param type - The blog post type to include in the feed.
+ * @param rssTitle - The title of the RSS feed.
+ * @param desc - A description of the RSS feed.
+ * @param outputPath - The file path where the generated RSS feed should be saved.
  *
- * @param {BlogPostTypes} type - The type of blog posts to include in the RSS feed.
- * @param {string} rssTitle - The title of the RSS feed.
- * @param {string} desc - The description of the RSS feed.
- * @param {string} outputPath - The output path for the generated RSS feed file.
- * @throws {Error} - Throws an error if there is an issue during the RSS feed generation.
+ * @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(type: BlogPostTypes, rssTitle: string, desc: string, outputPath: string) {
   try {