Add heading comments

Author: kraenhansen

packages/weak-node-api/scripts/generate-weak-node-api.ts

@@ -17,15 +17,30 @@ type GenerateFileOptions = {
   functions: FunctionDecl[];
   fileName: string;
   generator: (functions: FunctionDecl[]) => string;
+  headingComment?: string;
 };
 
 async function generateFile({
   functions,
   fileName,
   generator,
+  headingComment = "",
 }: GenerateFileOptions) {
   const generated = generator(functions);
-  const output = `// This file is generated - don't edit it directly\n\n${generated}`;
+  const output = `
+    /**
+     * @file ${fileName}
+     * ${headingComment
+       .trim()
+       .split("\n")
+       .map((l) => l.trim())
+       .join("\n* ")}
+     *
+     * @note This file is generated - don't edit it directly
+     */
+
+    ${generated}
+  `;
   const outputPath = path.join(OUTPUT_PATH, fileName);
   await fs.promises.writeFile(outputPath, output, "utf-8");
   const { status, stderr = "No error output" } = cp.spawnSync(
@@ -46,21 +61,41 @@ async function run() {
     functions,
     fileName: "weak_node_api.hpp",
     generator: weakNodeApiGenerator.generateHeader,
+    headingComment: `
+      @brief Weak Node-API host injection interface.
+     
+      This header provides the struct and injection function for deferring Node-API function calls from addons into a Node-API host.
+    `,
   });
   await generateFile({
     functions,
     fileName: "weak_node_api.cpp",
     generator: weakNodeApiGenerator.generateSource,
+    headingComment: `
+      @brief Weak Node-API host injection implementation.
+     
+      Provides the implementation for deferring Node-API function calls from addons into a Node-API host.
+    `,
   });
   await generateFile({
     functions,
     fileName: "weak_node_api_multi_host.hpp",
     generator: multiHostGenerator.generateHeader,
+    headingComment: `
+      @brief Weak Node-API multi-host injection interface.
+     
+      This header provides the struct for deferring Node-API function calls from addons into multiple Node-API host implementations.
+    `,
   });
   await generateFile({
     functions,
     fileName: "weak_node_api_multi_host.cpp",
     generator: multiHostGenerator.generateSource,
+    headingComment: `
+      @brief Weak Node-API multi-host injection implementation.
+     
+      Provides the implementation for deferring Node-API function calls from addons into multiple Node-API host implementations.
+    `,
   });
 }