Print heading comments in generated files

Author: kraenhansen

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

@@ -17,17 +17,32 @@ 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");
+  await fs.promises.writeFile(outputPath, output.trim(), "utf-8");
   const { status, stderr = "No error output" } = cp.spawnSync(
     "clang-format",
     ["-i", outputPath],
@@ -56,6 +71,11 @@ 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,