refactor: add @fileoverviews and structured comments to .js files (…

…#145)

This pull request includes several documentation improvements and code
organization changes across multiple files to enhance readability and
maintainability. The most important changes include adding file-level
JSDoc comments, organizing code sections with comments, and ensuring
consistent exports.

Documentation improvements:

*
[`packages/clang-format-git-python/src/cli.js`](diffhunk://#diff-93f1a01c7f4ac5a2380112cca516851320758c8184f96cddb10e1cc97012a468R3-R20):
Added a file-level JSDoc comment to provide an overview of the file's
purpose.
*
[`packages/clang-format-git-python/src/index.js`](diffhunk://#diff-a202f64e2597b71a2483e065b1814003935fc1f355d7678ed5153154e31b73adR1-R17):
Added a file-level JSDoc comment to describe the entry file for the
package.
*
[`packages/clang-format-git-python/src/utils/gitClangFormatPath.js`](diffhunk://#diff-0b92886b850ec05cf8174fb293fc1d7f26dfd6064e907bfc81e09da43c8e1e49R1-R14):
Added a file-level JSDoc comment to explain the APIs provided by the
file.

Code organization:

*
[`packages/clang-format-git/src/cli.js`](diffhunk://#diff-63ba214e13f2c5ab6dd124bf509fd488f9e2c9480f2db2c0e8293f0f38887bd7R3-R20):
Added comments to separate require and execution sections, and included
a file-level JSDoc comment.
*
[`packages/clang-format-git/src/utils/getGitClangFormatPath.js`](diffhunk://#diff-1bb2e643c38d95e89f5956f9701352544d048ce9b211521186d0aecda6a2b09bR1-R15):
Added comments to organize require, declaration, and export sections,
and included a file-level JSDoc comment.

packages/clang-format-git-python/src/cli.js

@@ -1,11 +1,23 @@
 #!/usr/bin/env node
 
+/**
+ * @fileoverview Entry file for the `npx git-clang-format` or `npx clang-format-git-python` command. See the `bin` property in `package.json`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { spawn } = require('child_process');
 
 const { clangFormatPath } = require('clang-format-node');
 
 const { gitClangFormatPath } = require('./utils/gitClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Execution
+// --------------------------------------------------------------------------------
+
 const spawned = spawn(
   'python',
   // Both `--binary=path/to/the/binary` and `--binary path/to/the/binary` commands are valid (the only difference is the `=`).

packages/clang-format-git-python/src/index.js

@@ -1,8 +1,20 @@
+/**
+ * @fileoverview Entry file for the `clang-format-git-python` package.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const {
   gitClangFormatPath,
   clangFormatGitPythonPath,
 } = require('./utils/gitClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Exports
+// --------------------------------------------------------------------------------
+
 module.exports = {
   gitClangFormatPath,
   clangFormatGitPythonPath,

packages/clang-format-git-python/src/utils/gitClangFormatPath.js

@@ -1,5 +1,17 @@
+/**
+ * @fileoverview `gitClangFormatPath` and `clangFormatGitPythonPath` APIs.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { resolve } = require('path');
 
+// --------------------------------------------------------------------------------
+// Declaration
+// --------------------------------------------------------------------------------
+
 /**
  * The ABSOLUTE path to the [`git-clang-format`](https://github.com/lumirlumir/npm-clang-format-node/blob/main/packages/clang-format-git-python/src/script/git-clang-format) Python script.
  *
@@ -17,6 +29,10 @@ const gitClangFormatPath = resolve(__dirname, `..`, `script`, `git-clang-format`
  */
 const clangFormatGitPythonPath = gitClangFormatPath;
 
+// --------------------------------------------------------------------------------
+// Exports
+// --------------------------------------------------------------------------------
+
 module.exports = {
   gitClangFormatPath,
   clangFormatGitPythonPath,

packages/clang-format-git/src/cli.js

@@ -1,11 +1,23 @@
 #!/usr/bin/env node
 
+/**
+ * @fileoverview Entry file for the `npx git-clang-format` or `npx clang-format-git` command. See the `bin` property in `package.json`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { spawn } = require('child_process');
 
 const { clangFormatPath } = require('clang-format-node');
 
 const { gitClangFormatPath } = require('./utils/gitClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Execution
+// --------------------------------------------------------------------------------
+
 const spawned = spawn(
   gitClangFormatPath,
   [`--binary=${clangFormatPath}`, ...process.argv.slice(2)],

packages/clang-format-git/src/index.js

@@ -1,9 +1,21 @@
+/**
+ * @fileoverview Entry file for the `clang-format-git` package.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const {
   getGitClangFormatPath,
   getClangFormatGitPath,
 } = require('./utils/getGitClangFormatPath');
 const { gitClangFormatPath, clangFormatGitPath } = require('./utils/gitClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Exports
+// --------------------------------------------------------------------------------
+
 module.exports = {
   getGitClangFormatPath,
   getClangFormatGitPath,

packages/clang-format-git/src/utils/getGitClangFormatPath.js

@@ -1,6 +1,18 @@
+/**
+ * @fileoverview `getGitClangFormatPath` and `getClangFormatGitPath` APIs.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { existsSync } = require('fs');
 const { resolve } = require('path');
 
+// --------------------------------------------------------------------------------
+// Declaration
+// --------------------------------------------------------------------------------
+
 /**
  * Returns the ABSOLUTE path to the `git-clang-format` executable binary based on the OS platform and architecture.
  *
@@ -40,6 +52,10 @@ function getGitClangFormatPath(osPlatform, architecture) {
  */
 const getClangFormatGitPath = getGitClangFormatPath;
 
+// --------------------------------------------------------------------------------
+// Exports
+// --------------------------------------------------------------------------------
+
 module.exports = {
   getGitClangFormatPath,
   getClangFormatGitPath,

packages/clang-format-git/src/utils/gitClangFormatPath.js

@@ -1,7 +1,19 @@
+/**
+ * @fileoverview `gitClangFormatPath` and `clangFormatGitPath` APIs.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { platform, arch } = require('os');
 
 const { getGitClangFormatPath } = require('./getGitClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Declaration
+// --------------------------------------------------------------------------------
+
 /**
  * The ABSOLUTE path to the `git-clang-format` executable binary based on the OS platform and architecture.
  *
@@ -18,6 +30,10 @@ const gitClangFormatPath = getGitClangFormatPath(platform(), arch());
  */
 const clangFormatGitPath = gitClangFormatPath;
 
+// --------------------------------------------------------------------------------
+// Exports
+// --------------------------------------------------------------------------------
+
 module.exports = {
   gitClangFormatPath,
   clangFormatGitPath,

packages/clang-format-node/src/cli.js

@@ -1,10 +1,22 @@
 #!/usr/bin/env node
 // The shebang line `#!/usr/bin/env node` ensures the script runs with the correct Node.js interpreter across different environments.
 
+/**
+ * @fileoverview Entry file for the `npx clang-format` and `npx clang-format-node` command. See the `bin` property in `package.json`.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { spawn } = require('child_process');
 
 const { clangFormatPath } = require('./utils/clangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Execution
+// --------------------------------------------------------------------------------
+
 const spawned = spawn(clangFormatPath, process.argv.slice(2), {
   stdio: 'inherit',
 });

packages/clang-format-node/src/index.js

@@ -1,9 +1,21 @@
+/**
+ * @fileoverview Entry file for the `clang-format-node` package.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { clangFormatPath, clangFormatNodePath } = require('./utils/clangFormatPath');
 const {
   getClangFormatPath,
   getClangFormatNodePath,
 } = require('./utils/getClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Exports
+// --------------------------------------------------------------------------------
+
 module.exports = {
   clangFormatPath,
   clangFormatNodePath,

packages/clang-format-node/src/utils/clangFormatPath.js

@@ -1,7 +1,19 @@
+/**
+ * @fileoverview `clangFormatPath` and `clangFormatNodePath` APIs.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { platform, arch } = require('os');
 
 const { getClangFormatPath } = require('./getClangFormatPath');
 
+// --------------------------------------------------------------------------------
+// Declaration
+// --------------------------------------------------------------------------------
+
 /**
  * The ABSOLUTE path to the `clang-format` executable binary based on the OS platform and architecture.
  *
@@ -18,6 +30,10 @@ const clangFormatPath = getClangFormatPath(platform(), arch());
  */
 const clangFormatNodePath = clangFormatPath;
 
+// --------------------------------------------------------------------------------
+// Exports
+// --------------------------------------------------------------------------------
+
 module.exports = {
   clangFormatPath,
   clangFormatNodePath,

packages/clang-format-node/src/utils/getClangFormatPath.js

@@ -1,6 +1,18 @@
+/**
+ * @fileoverview `getClangFormatPath` and `getClangFormatNodePath` APIs.
+ */
+
+// --------------------------------------------------------------------------------
+// Require
+// --------------------------------------------------------------------------------
+
 const { existsSync } = require('fs');
 const { resolve } = require('path');
 
+// --------------------------------------------------------------------------------
+// Declaration
+// --------------------------------------------------------------------------------
+
 /**
  * Returns the ABSOLUTE path to the `clang-format` executable binary based on the OS platform and architecture.
  *
@@ -40,6 +52,10 @@ function getClangFormatPath(osPlatform, architecture) {
  */
 const getClangFormatNodePath = getClangFormatPath;
 
+// --------------------------------------------------------------------------------
+// Exports
+// --------------------------------------------------------------------------------
+
 module.exports = {
   getClangFormatPath,
   getClangFormatNodePath,