feature(banira): add a new approach at document generation

Author: Sebastian Schürmann

packages/banira/src/discover-comments.ts

@@ -0,0 +1,95 @@
+import {
+    Node,
+    SyntaxKind,
+    CommentRange,
+    getLeadingCommentRanges
+} from 'typescript';
+import { TextRange } from '@microsoft/tsdoc';
+
+export interface IFoundComment {
+    compilerNode: Node;
+    textRange: TextRange;
+}
+
+function isDeclarationKind(kind: SyntaxKind): boolean {
+    switch (kind) {
+        case SyntaxKind.ArrowFunction:
+        case SyntaxKind.BindingElement:
+        case SyntaxKind.ClassDeclaration:
+        case SyntaxKind.ClassExpression:
+        case SyntaxKind.Constructor:
+        case SyntaxKind.EnumDeclaration:
+        case SyntaxKind.EnumMember:
+        case SyntaxKind.ExportSpecifier:
+        case SyntaxKind.FunctionDeclaration:
+        case SyntaxKind.FunctionExpression:
+        case SyntaxKind.GetAccessor:
+        case SyntaxKind.ImportEqualsDeclaration:
+        case SyntaxKind.ImportSpecifier:
+        case SyntaxKind.InterfaceDeclaration:
+        case SyntaxKind.JsxAttribute:
+        case SyntaxKind.MethodDeclaration:
+        case SyntaxKind.MethodSignature:
+        case SyntaxKind.ModuleDeclaration:
+        case SyntaxKind.NamespaceExportDeclaration:
+        case SyntaxKind.NamespaceImport:
+        case SyntaxKind.Parameter:
+        case SyntaxKind.PropertyAssignment:
+        case SyntaxKind.PropertyDeclaration:
+        case SyntaxKind.PropertySignature:
+        case SyntaxKind.SetAccessor:
+        case SyntaxKind.ShorthandPropertyAssignment:
+        case SyntaxKind.TypeAliasDeclaration:
+        case SyntaxKind.TypeParameter:
+        case SyntaxKind.VariableDeclaration:
+        case SyntaxKind.JSDocTypedefTag:
+        case SyntaxKind.JSDocCallbackTag:
+        case SyntaxKind.JSDocPropertyTag:
+            return true;
+    }
+    return false;
+}
+
+function getJSDocCommentRanges(node: Node, text: string): CommentRange[] {
+    const commentRanges: CommentRange[] = [];
+
+    switch (node.kind) {
+        case SyntaxKind.Parameter:
+        case SyntaxKind.TypeParameter:
+        case SyntaxKind.FunctionExpression:
+        case SyntaxKind.ArrowFunction:
+        case SyntaxKind.ParenthesizedExpression:
+            return commentRanges;
+    }
+
+    // Collect comment ranges
+    const ranges: CommentRange[] | undefined = getLeadingCommentRanges(text, node.getFullStart());
+    if (ranges) {
+        commentRanges.push(...ranges);
+    }
+
+    return commentRanges;
+}
+
+/**
+ * Recursively walks through the TypeScript AST and discovers JSDoc comments associated with declaration nodes.
+ * 
+ * @param node - The TypeScript AST node to analyze
+ * @param foundComments - Array to collect discovered comments
+ */
+export function discoverComments(node: Node, foundComments: IFoundComment[]): void {
+    const buffer: string = node.getSourceFile().getFullText(); // don't use getText() here!
+    if (isDeclarationKind(node.kind)) {
+        const comments: CommentRange[] = getJSDocCommentRanges(node, buffer);
+
+        if (comments.length > 0) {
+            for (const comment of comments) {
+                foundComments.push({
+                    compilerNode: node,
+                    textRange: TextRange.fromStringRange(buffer, comment.pos, comment.end)
+                });
+            }
+        }
+    }
+    return node.forEachChild((child) => discoverComments(child, foundComments));
+}

packages/banira/src/formatter/doc-page.ts

@@ -1,4 +1,4 @@
-import { DocBlock, DocParamCollection, DocSection, ParserContext } from "@microsoft/tsdoc";
+import { DocBlock, DocParamCollection, DocSection, ParserContext, ParserMessage } from "@microsoft/tsdoc";
 
 export class FormatterDocPage { 
     private context: ParserContext;
@@ -11,6 +11,10 @@ export class FormatterDocPage {
         return this.context.docComment.customBlocks;
     }
 
+    get logs(): readonly ParserMessage[] {
+        return this.context.log.messages;
+    }
+
     get params(): DocParamCollection {
         return this.context.docComment.params
     }
@@ -33,8 +37,12 @@ export class FormatterDocPage {
     >
 </head>
 <body>
-    <h1>${title}</h1>
-    <${tagName}></${tagName}>
+    <header>
+        <h1>${title}</h1>
+    </header>
+    <main>
+        <${tagName}></${tagName}>
+    </main>
 </body>
 </html>`
     }

packages/banira/src/result-analyzer.ts

@@ -1,5 +1,16 @@
-import { Program, EmitResult, Diagnostic, SourceFile, CompilerOptions, DiagnosticCategory, formatDiagnosticsWithColorAndContext, sys, getPreEmitDiagnostics } from 'typescript';
+import { 
+    Program, 
+    EmitResult, 
+    Diagnostic, 
+    SourceFile, 
+    CompilerOptions, 
+    DiagnosticCategory, 
+    formatDiagnosticsWithColorAndContext, 
+    sys, 
+    getPreEmitDiagnostics
+} from 'typescript';
 import  { CompilerResult } from './compiler';
+import { discoverComments, IFoundComment } from './discover-comments.js';
 
 /**
  * Interface representing the result of diagnostic analysis
@@ -71,6 +82,14 @@ export class ResultAnalyzer {
         return this.program.getSourceFiles();
     }
 
+    get comments(): IFoundComment[] {
+        const foundComments: IFoundComment[] = [];
+        for (const sourceFile of this.program.getSourceFiles()) {
+            discoverComments(sourceFile, foundComments);
+        }
+        return foundComments;
+    }
+
     /**
      * Gets the paths of all emitted (output) files
      * 
@@ -105,7 +124,7 @@ export class ResultAnalyzer {
         const formatted = formatDiagnosticsWithColorAndContext(diagnostics, {
             getCurrentDirectory: () => process.cwd(),
             getCanonicalFileName: fileName => fileName,
-            getNewLine: () => sys.newLine
+            getNewLine:() => sys.newLine
         });
 
         return {
@@ -116,4 +135,4 @@ export class ResultAnalyzer {
             formatted
         }
     }
-}
+}

packages/banira/test/doc.gen.formatter-page.test.ts

@@ -14,17 +14,30 @@ describe('DocGen Formatter', () => {
         parsed = await docGen.parseDoc('./test/fixtures/my-circle.ts');
         formatter = new FormatterDocPage(parsed);
     })
-    it('should parse a typescript file and return a ParserContext', async () => {
-        assert.ok(parsed, 'ParserContext should be returned');
-    });
 
-    it('should create a doc page', async () => {
-        const result = formatter.createDocPage(docGen.tagName, docGen.src, docGen.title);
-        assert.ok(result, 'Doc page should be created');
-    });
+    it('customBlocks', async () => {   
+        assert.equal(formatter.custom.length, 1);
+    })
+
+    it('logs', async () => {   
+        assert.equal(formatter.logs.length, 0);
+    })
+
+    it('params', async () => {   
+        assert.ok(formatter.params);
+    })
 
-    it('contains the demo tag', async () => {
-        const result = formatter.createDocPage(docGen.tagName, docGen.src, docGen.title);
-        assert.match(result, /<my-circle><\/my-circle>/);
+    describe('createDocPage', () => {
+        let result: string;
+        before(async () => {
+            result = formatter.createDocPage(docGen.tagName, docGen.src, docGen.title);
+        });
+    
+        it('should create a doc page', async () => {
+            assert.ok(result, 'Doc page should be created');
+        });
+        it('contains the demo tag', async () => {
+            assert.match(result, /<my-circle><\/my-circle>/);
+        });
     });
 });

packages/banira/test/fixtures/my-circle.ts

@@ -1,14 +1,6 @@
 /**
  * A custom web component that renders a circle using SVG.
  * 
- * @example
- * ```html
- * <my-circle size="100" color="blue"></my-circle>
- * ```
- */
-/**
- * A demo of a custom web component that renders a circle using SVG.
- * 
  * @demo
  * ```html
  * <my-circle size="100" color="blue"></my-circle>

packages/banira/test/result-analyzer.test.ts

@@ -107,6 +107,17 @@ describe("ResultAnalyzer", () => {
         });
     });
 
+    describe("comments", () => {
+        it("extracts them", () => {
+            assert.ok(analyzer.comments);
+        });
+
+        it("gets > 10K comments", () => {
+            assert.ok(analyzer.comments.length>1000);
+        });
+    }); 
+
+
     describe("output files", () => {
         it("should provide output files as an array", () => {
             assert.ok(

packages/component-webaudio/package.json

@@ -10,7 +10,8 @@
     "build": "tsc",
     "build:banira": "banira compile --project ./tsconfig.json --outDir ./dist ./src/wa-knob.ts",
     "predemo": "rm -rf ./demo && mkdir ./demo && cp -r ./dist/ ./demo/dist/",
-    "demo": "banira doc ./src/wa-knob.ts > ./demo/index.html"
+    "demo": "banira doc ./src/wa-knob.ts > ./demo/index.html",
+    "server": "npx -y http-server ./demo"
   },
   "keywords": [
     "web-components",