From dd9ee304256ef39abe4753e1b738729d4339f08f Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Tue, 27 May 2025 20:24:59 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`bump-pa?=
 =?UTF-8?q?rtials`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @JakeSCahill.

* https://github.com/redpanda-data/docs-ui/pull/295#issuecomment-2913930359

The following files were modified:

* `compile-partial.js`
* `gulpfile.js`
---
 compile-partial.js |  8 ++++++++
 gulpfile.js        | 12 ++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/compile-partial.js b/compile-partial.js
index 293bf046..cc5070f1 100644
--- a/compile-partial.js
+++ b/compile-partial.js
@@ -13,6 +13,14 @@ if (fs.existsSync(helpersDir)) {
   });
 }
 
+/**
+ * Reads and parses a JSON file from the specified path.
+ *
+ * If the file cannot be read or parsed, returns an empty object.
+ *
+ * @param {string} filepath - Path to the JSON file.
+ * @returns {Object} The parsed JSON object, or an empty object if reading or parsing fails.
+ */
 function readJson(filepath) {
   try {
     return JSON.parse(fs.readFileSync(filepath, 'utf8'));
diff --git a/gulpfile.js b/gulpfile.js
index 7f3f1cc1..645a387b 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -28,6 +28,13 @@ const glob = {
 const rapidocSrc = 'node_modules/rapidoc/dist/rapidoc-min.js'
 const rapidocDest = path.join(srcDir, 'static')
 
+/**
+ * Compiles Handlebars partial templates by executing a Node.js script for each specified partial.
+ *
+ * @param {Function} cb - Callback to signal task completion or failure.
+ *
+ * @throws {Error} If any partial compilation fails, the callback is invoked with an error.
+ */
 function compileWidgets (cb) {
   const partialsToCompile = [
     { name: 'header-content', context: 'context/header-content.json' },
@@ -50,6 +57,11 @@ function compileWidgets (cb) {
   }
 }
 
+/**
+ * Copies the Rapidoc JavaScript file from the source location to the static assets directory.
+ *
+ * @returns {Stream} A Gulp stream representing the copy operation.
+ */
 function copyRapidoc () {
   return gulp.src(rapidocSrc)
     .pipe(gulp.dest(rapidocDest))