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

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,