improve landing pages and clean rendered signatures

Author: auscaster

README.md

@@ -15,6 +15,7 @@ Doxygen XML to Markdown converter for C++ and Java developers who want minimal,
 - **Markdown comments** - Markdown in Doxygen comments is rendered
 - **Doxygen groups** - [grouping](http://www.doxygen.nl/manual/grouping.html) support for organised docs
 - **Grouped and ungrouped codebases** - works with explicit grouped compounds and normal namespace/class output
+- **Structured landing pages** - namespace and group pages separate nested namespaces, types, and enums
 - **Custom templates** - modify the Handlebars templates to suit your needs
 - **Optional index** - optionally render a top-level index
 

src/helpers.ts

@@ -47,6 +47,13 @@ export function inline(code: string | string[]): string {
   return s + (isInline ? '`' : '');
 }
 
+/**
+ * Strip markdown links from generated type/signature text while preserving labels.
+ */
+export function stripMarkdownLinks(text: string): string {
+  return (text || '').replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+}
+
 /**
  * Generate an anchor string based on options.
  */

src/templates.ts

@@ -8,7 +8,7 @@
 import { readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import Handlebars from 'handlebars';
-import { getAnchor, cleanId } from './helpers.js';
+import { getAnchor, cleanId, stripMarkdownLinks } from './helpers.js';
 import type { AnchorMap } from './helpers.js';
 import { log } from './logger.js';
 import type { Compound, MoxygenOptions } from './types.js';
@@ -37,6 +37,25 @@ export function registerHelpers(options: Pick<MoxygenOptions, 'anchors' | 'htmlA
 
   Handlebars.registerHelper('or', (a: unknown, b: unknown) => a || b);
 
+  Handlebars.registerHelper('compoundsOfKind', (compounds: unknown, ...args: unknown[]) => {
+    const options = args[args.length - 1];
+    void options;
+    const kinds = new Set(
+      args
+        .slice(0, -1)
+        .filter((value): value is string => typeof value === 'string'),
+    );
+    if (!Array.isArray(compounds) || !kinds.size) {
+      return [];
+    }
+    return compounds.filter((compound) =>
+      compound &&
+      typeof compound === 'object' &&
+      'kind' in compound &&
+      kinds.has((compound as Record<string, unknown>).kind as string),
+    );
+  });
+
   Handlebars.registerHelper('shortname', (fullname: string) => {
     const parts = (fullname || '').split('::');
     return parts[parts.length - 1] || fullname;
@@ -52,27 +71,35 @@ export function registerHelpers(options: Pick<MoxygenOptions, 'anchors' | 'htmlA
     if (kind === 'variable') {
       const init = member.initializer as string;
       return init
-        ? `${member.returnType} ${member.name} ${init}`
-        : `${member.returnType} ${member.name}`;
+        ? `${stripMarkdownLinks(member.returnType as string)} ${member.name} ${init}`
+        : `${stripMarkdownLinks(member.returnType as string)} ${member.name}`;
     }
     if (kind === 'property') {
-      return `${member.returnType} ${member.name}`;
+      return `${stripMarkdownLinks(member.returnType as string)} ${member.name}`;
     }
 
     // function/signal/slot
     const parts: string[] = [];
     const tparams = member.templateParams as Array<{ type: string; name: string }>;
     if (tparams && tparams.length > 0) {
-      parts.push('template<' + tparams.map(tp => tp.name ? `${tp.type} ${tp.name}` : tp.type).join(', ') + '>');
+      parts.push('template<' + tparams.map(tp => {
+        const type = stripMarkdownLinks(tp.type);
+        return tp.name ? `${type} ${tp.name}` : type;
+      }).join(', ') + '>');
     }
     if (member.isVirtual) parts.push('virtual');
     if (member.isStatic) parts.push('static');
     if (member.isInline) parts.push('inline');
     if (member.isExplicit) parts.push('explicit');
     const rt = member.returnType as string;
-    if (rt) parts.push(rt);
+    if (rt) parts.push(stripMarkdownLinks(rt));
     const params = member.params as Array<{ type: string; name: string }>;
-    const paramStr = params ? params.map(p => p.name ? `${p.type} ${p.name}` : p.type).join(', ') : '';
+    const paramStr = params
+      ? params.map((p) => {
+        const type = stripMarkdownLinks(p.type);
+        return p.name ? `${type} ${p.name}` : type;
+      }).join(', ')
+      : '';
     parts.push(`${member.name}(${paramStr})`);
     const qualifiers = member.qualifiers as string[];
     if (qualifiers) {

templates/cpp/namespace.md

@@ -10,14 +10,38 @@
 {{detaileddescription}}
 {{/if}}
 
-{{#if filtered.compounds}}
+{{#with (compoundsOfKind filtered.compounds "namespace") as |namespaces|}}
+{{#if namespaces}}
+### Namespaces
+
+| Name | Description |
+|------|-------------|
+{{#each namespaces}}| [`{{shortname name}}`](#{{cleanId refid name}}) | {{cell summary}} |
+{{/each}}
+{{/if}}
+{{/with}}
+
+{{#with (compoundsOfKind filtered.compounds "class" "struct" "interface") as |types|}}
+{{#if types}}
 ### Classes
 
 | Name | Description |
 |------|-------------|
-{{#each filtered.compounds}}| [`{{shortname name}}`](#{{cleanId refid name}}) | {{cell summary}} |
+{{#each types}}| [`{{shortname name}}`](#{{cleanId refid name}}) | {{cell summary}} |
+{{/each}}
+{{/if}}
+{{/with}}
+
+{{#with (compoundsOfKind filtered.compounds "enum") as |enums|}}
+{{#if enums}}
+### Enumerations
+
+| Name | Description |
+|------|-------------|
+{{#each enums}}| [`{{shortname name}}`](#{{cleanId refid name}}) | {{cell summary}} |
 {{/each}}
 {{/if}}
+{{/with}}
 
 {{#each filtered.sections}}
 ### {{label}}

templates/java/namespace.md

@@ -10,14 +10,38 @@
 {{detaileddescription}}
 {{/if}}
 
-{{#if filtered.compounds}}
+{{#with (compoundsOfKind filtered.compounds "namespace") as |namespaces|}}
+{{#if namespaces}}
+### Namespaces
+
+| Name | Description |
+|------|-------------|
+{{#each namespaces}}| [`{{shortname name}}`](#{{cleanId refid name}}) | {{cell summary}} |
+{{/each}}
+{{/if}}
+{{/with}}
+
+{{#with (compoundsOfKind filtered.compounds "class" "struct" "interface") as |types|}}
+{{#if types}}
 ### Classes
 
 | Name | Description |
 |------|-------------|
-{{#each filtered.compounds}}| [`{{shortname name}}`](#{{cleanId refid name}}) | {{cell summary}} |
+{{#each types}}| [`{{shortname name}}`](#{{cleanId refid name}}) | {{cell summary}} |
+{{/each}}
+{{/if}}
+{{/with}}
+
+{{#with (compoundsOfKind filtered.compounds "enum") as |enums|}}
+{{#if enums}}
+### Enumerations
+
+| Name | Description |
+|------|-------------|
+{{#each enums}}| [`{{shortname name}}`](#{{cleanId refid name}}) | {{cell summary}} |
 {{/each}}
 {{/if}}
+{{/with}}
 
 {{#each filtered.sections}}
 ### {{label}}

test/helpers.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { inline, getAnchor, findParent } from '../src/helpers.js';
+import { inline, getAnchor, findParent, stripMarkdownLinks } from '../src/helpers.js';
 import { createCompound } from '../src/compound.js';
 
 describe('helpers', () => {
@@ -65,4 +65,11 @@ describe('helpers', () => {
       expect(result).toBeUndefined();
     });
   });
+
+  describe('stripMarkdownLinks', () => {
+    it('replaces markdown links with their labels', () => {
+      const input = '[TrackHandle](#trackhandle) func([PeerSession::State](#state) state)';
+      expect(stripMarkdownLinks(input)).toBe('TrackHandle func(PeerSession::State state)');
+    });
+  });
 });

test/integration.test.ts

@@ -93,6 +93,7 @@ describe('integration', () => {
     expect(content.length).toBeGreaterThan(0);
     expect(content).toContain('# widget');
     expect(content).toContain('Module page for a widget API documented with file-level grouping.');
+    expect(content).toContain('### Namespaces');
     expect(content).toContain('documented via file-level grouping only.');
     expect(content).toContain('createWidget');
     expect(content).toContain('Returns the current widget size.');