docs: Add support for "experimental" docs tag

docs/README.md

@@ -90,6 +90,12 @@ class.
 
 The @since tag indicates that a class, method, or other symbol was added in a specific version.
 
+##### `@experimental`
+
+The @experimental tag indicates that a class, method, or other symbol is part of an experimental API and 
+may be subject to changes. This is used to allow the testing of new features to gather developer feedback before
+marking the API as stable
+
 ##### Example
 
 ````ts
@@ -106,6 +112,7 @@ The @since tag indicates that a class, method, or other symbol was added in a sp
  * ```
  *
  * @docsCategory helpers
+ * @since 1.2.3
  */
 export class Greeter {
 

scripts/docs/typescript-docgen-types.ts

@@ -14,6 +14,7 @@ export interface MemberInfo {
     fullText: string;
     modifiers: string[];
     since: string | undefined;
+    experimental: boolean;
 }
 
 export interface PropertyInfo extends MemberInfo {
@@ -44,6 +45,7 @@ export interface DeclarationInfo {
     description: string;
     page: string | undefined;
     since: string | undefined;
+    experimental: boolean;
 }
 
 export interface InterfaceInfo extends DeclarationInfo {

scripts/docs/typescript-docs-parser.ts

@@ -111,6 +111,7 @@ export class TypescriptDocsParser {
         const description = this.getDeclarationDescription(statement);
         const docsPage = this.getDocsPage(statement);
         const since = this.getSince(statement);
+        const experimental = this.getExperimental(statement);
         const packageName = this.getPackageName(sourceFile);
 
         const info = {
@@ -124,6 +125,7 @@ export class TypescriptDocsParser {
             description,
             page: docsPage,
             since,
+            experimental,
         };
 
         if (ts.isInterfaceDeclaration(statement)) {
@@ -226,7 +228,7 @@ export class TypescriptDocsParser {
     }
 
     /**
-     * Parses an array of inteface members into a simple object which can be rendered into markdown.
+     * Parses an array of interface members into a simple object which can be rendered into markdown.
      */
     private parseMembers(
         members: ts.NodeArray<ts.TypeElement | ts.ClassElement | ts.EnumMember>,
@@ -259,6 +261,7 @@ export class TypescriptDocsParser {
                 let fullText = '';
                 let isInternal = false;
                 let since: string | undefined;
+                let experimental = false;
                 if (ts.isConstructorDeclaration(member)) {
                     fullText = 'constructor';
                 } else if (ts.isMethodDeclaration(member)) {
@@ -274,6 +277,7 @@ export class TypescriptDocsParser {
                     default: comment => (defaultValue = comment || ''),
                     internal: comment => (isInternal = true),
                     since: comment => (since = comment || undefined),
+                    experimental: comment => (experimental = comment != null),
                 });
                 if (isInternal) {
                     continue;
@@ -288,6 +292,7 @@ export class TypescriptDocsParser {
                     type,
                     modifiers,
                     since,
+                    experimental,
                 };
                 if (
                     ts.isMethodSignature(member) ||
@@ -358,6 +363,17 @@ export class TypescriptDocsParser {
         return since;
     }
 
+    /**
+     * Reads the @experimental JSDoc tag
+     */
+    private getExperimental(statement: ValidDeclaration): boolean {
+        let experimental = false;
+        this.parseTags(statement, {
+            experimental: comment => (experimental = comment != null),
+        });
+        return experimental;
+    }
+
     /**
      * Reads the @description JSDoc tag from the interface.
      */

scripts/docs/typescript-docs-renderer.ts

@@ -283,6 +283,7 @@ export class TypescriptDocsRenderer {
         for (const member of members || []) {
             let defaultParam = '';
             let sinceParam = '';
+            let experimentalParam = '';
             let type = '';
             if (member.kind === 'property') {
                 type = this.renderType(member.type, knownTypeMap, docsUrl);
@@ -302,10 +303,13 @@ export class TypescriptDocsRenderer {
             if (member.since) {
                 sinceParam = `since="${member.since}" `;
             }
+            if (member.experimental) {
+                experimentalParam = 'experimental="true"';
+            }
             output += `### ${member.name}\n\n`;
             output += `{{< member-info kind="${[...member.modifiers, member.kind].join(
                 ' ',
-            )}" type="${type}" ${defaultParam} ${sinceParam}>}}\n\n`;
+            )}" type="${type}" ${defaultParam} ${sinceParam}${experimentalParam}>}}\n\n`;
             output += `{{< member-description >}}${this.renderDescription(
                 member.description,
                 knownTypeMap,
@@ -334,7 +338,11 @@ export class TypescriptDocsRenderer {
         if (info.since) {
             sinceData = ` since="${info.since}"`;
         }
-        return `{{< generation-info sourceFile="${sourceFile}" sourceLine="${info.sourceLine}" packageName="${info.packageName}"${sinceData}>}}\n\n`;
+        let experimental = '';
+        if (info.experimental) {
+            experimental = ` experimental="true"`;
+        }
+        return `{{< generation-info sourceFile="${sourceFile}" sourceLine="${info.sourceLine}" packageName="${info.packageName}"${sinceData}${experimental}>}}\n\n`;
     }
 
     /**