feat(jsdocs): sections and sorting

Author: pi0

README.md

@@ -47,7 +47,7 @@ The declared section will be automatically updated!
 ### Supported Args
 
 - `src`: Path to the source file. The default is `./src/index` and can be omitted.
-- `headingLevel`: Nested level for markdown headings (default is `3` => `###`)
+- `headingLevel`: Nested level for markdown group headings (default is `3` => `###`) - Note: Each export uses `headingLevel+1`.
 
 ## Development
 

playground/README.md

@@ -2,7 +2,7 @@
 
 <!-- AUTOMD_START generator="jsdocs" src="./src/index" -->
 
-### `add(a, b)`
+#### `add(a, b)`
 
 Adds two numbers together.
 

src/generators/jsdocs.ts

@@ -19,13 +19,19 @@ export default defineGenerator({
 });
 
 function renderSchema(schema: Schema, opts: { headingLevel: number }) {
-  const md: string[] = [];
+  const sections = Object.create(null) as Record<string, [string, string[]][]>;
+
   for (const [name, meta] of Object.entries(schema.properties || {})) {
     // Only functions
-    if (meta.type !== "function") {
+    if (
+      meta.type !== "function" ||
+      meta.default?.toString?.().startsWith("class")
+    ) {
       continue;
     }
 
+    const lines: string[] = [];
+
     // Parse tag annotations
     const tags = parseTags(meta.tags);
 
@@ -36,28 +42,44 @@ function renderSchema(schema: Schema, opts: { headingLevel: number }) {
 
     const jsSig = `${name}(${(meta.args || []).map((arg) => arg.name).join(", ")})`;
 
-    md.push(`${"#".repeat(opts.headingLevel)} \`${jsSig}\``, "");
+    lines.push(`${"#".repeat(opts.headingLevel + 1)} \`${jsSig}\``, "");
 
     if (meta.title) {
-      md.push(meta.title.trim());
+      lines.push(meta.title.trim());
     }
     if (meta.description) {
-      md.push("", meta.description.trim());
+      lines.push("", meta.description.trim());
     }
 
     for (const tag of tags) {
       if (tag.tag === "@example") {
         const codeBlock = tag.contents.startsWith("`")
           ? tag.contents
           : `\`\`\`ts\n${tag.contents}\n\`\`\``;
-        md.push("", "**Example:**", "", codeBlock);
+        lines.push("", "**Example:**", "", codeBlock);
       }
     }
 
-    md.push("");
+    lines.push("");
+
+    const group = tags.find((t) => t.tag === "@group")?.contents || "";
+    sections[group] = sections[group] || [];
+    sections[group].push([name, lines]);
+  }
+
+  const lines: string[] = [];
+  for (const group of Object.keys(sections).sort()) {
+    if (group) {
+      lines.push(`${"#".repeat(opts.headingLevel)} ${group}`, "");
+    }
+    for (const item of sections[group].sort((i1, i2) =>
+      i1[0].localeCompare(i2[0]),
+    )) {
+      lines.push(...item[1]);
+    }
   }
 
-  return md.join("\n");
+  return lines.join("\n");
 }
 
 function parseTags(lines: string[] = []) {