feature(vanillin): add a own doctag for demo cases

Author: Sebastian Schürmann

packages/vanillin/src/doc-gen.ts

@@ -1,12 +1,25 @@
-import { TSDocParser, type ParserContext, type DocComment } from '@microsoft/tsdoc';
+import { TSDocParser, type ParserContext, type DocComment, TSDocConfiguration, TSDocTagDefinition, TSDocTagSyntaxKind } from '@microsoft/tsdoc';
 import * as path from 'path';
 import * as fs from 'fs';
 import { Formatter } from './formatter';
 export class DocGen {
+
     parseDoc(doc: string): ParserContext {
         const inputFilename: string = path.resolve(doc);
         const inputBuffer: string = fs.readFileSync(inputFilename).toString();
-        const tsdocParser: TSDocParser = new TSDocParser();
+        
+        const customConfiguration: TSDocConfiguration = new TSDocConfiguration();
+        
+        const customBlockDefinition: TSDocTagDefinition = new TSDocTagDefinition({
+            tagName: '@demo',
+            syntaxKind: TSDocTagSyntaxKind.BlockTag
+        });
+
+        customConfiguration.addTagDefinitions([
+            customBlockDefinition
+        ]);
+
+        const tsdocParser: TSDocParser = new TSDocParser(customConfiguration);
         const parserContext: ParserContext = tsdocParser.parseString(inputBuffer);
         return parserContext;
     }
@@ -16,4 +29,10 @@ export class DocGen {
         const result = Formatter.renderDocNodes(docComment.getChildNodes());
         return result;
     }
+
+    renderDocs(context: ParserContext) {
+        const docComment: DocComment = context.docComment;
+        const result = Formatter.renderDocNodes(docComment.customBlocks);
+        return result;
+    }
 }

packages/vanillin/test/doc-gen.test.ts

@@ -8,4 +8,17 @@ describe('DocGen', () => {
         const result = docGen.parseDoc('./test/fixtures/my-circle.ts');
         assert.ok(result, 'ParserContext should be returned');
     });
+
+    it('returns the demo tag', () => {
+        const docGen = new DocGen();
+        const result = docGen.parseDoc('./test/fixtures/my-circle.ts');
+        assert.equal(result.docComment.customBlocks.length, 1);
+    });
+
+    it('rendered result contains tag', () => {
+        const docGen = new DocGen();
+        const result = docGen.parseDoc('./test/fixtures/my-circle.ts');
+        const doc = docGen.renderDocs(result);
+        assert.match(doc, /my-circle/);
+    });
 });

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

@@ -6,6 +6,14 @@
  * <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>
+ * ```
+ */
 class MyCircle extends HTMLElement {
     /** The diameter of the circle in pixels. Default is 50. */
     private _size: number = 50;