fix(api-markdown-documenter): Include missing property/variable type …

…information to "details" sections (#20782) Affects default transformation implementations. Adds content like the following to the "Signature" section of property/variable details sections: ```markdown Type: boolean ``` These sections will include hyperlinks to the relevant type details for types defined in the API model.
microsoft · Apr 22, 2024 · 6967b02 · 6967b02
1 parent 0a9b9ab
commit 6967b02
Show file tree

Hide file tree

Showing 49 changed files with 275 additions and 1 deletion.
diff --git a/tools/api-markdown-documenter/CHANGELOG.md b/tools/api-markdown-documenter/CHANGELOG.md
@@ -2,7 +2,8 @@
 
 ## 0.12.2
 
--   Fixed an issue where variable item tables did not include type information.
+-   Fixed an issue where variable item tables did not include type information in default ApiItem transformations.
+-   Add variable and property type information to associated details sections in default ApiItem transformations.
 -   Further improved error messages when an unexpected child kind is encountered when iterating over children in default ApiItem transformations.
 
 ## 0.12.1

diff --git a/tools/api-markdown-documenter/src/api-item-transforms/helpers/Helpers.ts b/tools/api-markdown-documenter/src/api-item-transforms/helpers/Helpers.ts
@@ -18,6 +18,8 @@ import {
 	type HeritageType,
 	type IResolveDeclarationReferenceResult,
 	type TypeParameter,
+	ApiPropertyItem,
+	ApiVariable,
 } from "@microsoft/api-extractor-model";
 import {
 	type DocNode,
@@ -198,6 +200,17 @@ export function createHeritageTypesParagraph(
 		}
 	}
 
+	// Render type information for properties and variables
+	let renderedTypeSpan: SpanNode | undefined;
+	if (apiItem instanceof ApiPropertyItem) {
+		renderedTypeSpan = createTypeSpan(apiItem.propertyTypeExcerpt, config);
+	} else if (apiItem instanceof ApiVariable) {
+		renderedTypeSpan = createTypeSpan(apiItem.variableTypeExcerpt, config);
+	}
+	if (renderedTypeSpan !== undefined) {
+		contents.push(new ParagraphNode([renderedTypeSpan]));
+	}
+
 	// Render type parameters if there are any.
 	if (ApiTypeParameterListMixin.isBaseClassOf(apiItem) && apiItem.typeParameters.length > 0) {
 		const renderedTypeParameters = createTypeParametersSection(
@@ -220,6 +233,28 @@ export function createHeritageTypesParagraph(
 	return new ParagraphNode(contents);
 }
 
+/**
+ * Renders a labeled type-information entry.
+ *
+ * @remarks Displayed as `Type: <type>`. Type excerpt will be rendered with the appropriate hyperlinks for other types in the API model.
+ *
+ * @param excerpt - The type excerpt to be displayed.
+ * @param config - See {@link ApiItemTransformationConfiguration}.
+ */
+function createTypeSpan(
+	excerpt: Excerpt,
+	config: Required<ApiItemTransformationConfiguration>,
+): SpanNode | undefined {
+	if (!excerpt.isEmpty) {
+		const renderedLabel = SpanNode.createFromPlainText(`Type: `, { bold: true });
+		const renderedExcerpt = createExcerptSpanWithHyperlinks(excerpt, config);
+		if (renderedExcerpt !== undefined) {
+			return new SpanNode([renderedLabel, renderedExcerpt]);
+		}
+	}
+	return undefined;
+}
+
 /**
  * Renders a labeled, comma-separated list of heritage types.
  *

diff --git a/tools/api-markdown-documenter/src/api-item-transforms/test/Transformation.test.ts b/tools/api-markdown-documenter/src/api-item-transforms/test/Transformation.test.ts
@@ -369,15 +369,23 @@ describe("ApiItem to Documentation transformation tests", () => {
 				[
 					wrapInSection(
 						[
+							// Summary section
 							wrapInSection([
 								ParagraphNode.createFromPlainText("Test optional property"),
 							]),
+							// Signature section
 							wrapInSection(
 								[
 									FencedCodeBlockNode.createFromPlainText(
 										"testOptionalInterfaceProperty?: number;",
 										"typescript",
 									),
+									new ParagraphNode([
+										new SpanNode([
+											SpanNode.createFromPlainText("Type: ", { bold: true }),
+											SpanNode.createFromPlainText("number"),
+										]),
+									]),
 								],
 								{
 									title: "Signature",

diff --git a/...ocumenter/src/test/snapshots/html/simple-suite-test/default-config/simple-suite-test.html b/...ocumenter/src/test/snapshots/html/simple-suite-test/default-config/simple-suite-test.html
@@ -959,6 +959,9 @@ <h4 id="testconstwithemptydeprecatedblock-signature">
             <code>
               testConstWithEmptyDeprecatedBlock: string
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>string</span></span>
+            </p>
           </section>
         </section>
       </section>

diff --git a/...hots/html/simple-suite-test/default-config/simple-suite-test/testabstractclass-class.html b/...hots/html/simple-suite-test/default-config/simple-suite-test/testabstractclass-class.html
@@ -258,6 +258,9 @@ <h4 id="abstractpropertygetter-signature">
             <code>
               abstract get abstractPropertyGetter(): TestMappedType;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span><a href='./simple-suite-test#testmappedtype-typealias'>TestMappedType</a></span></span>
+            </p>
           </section>
         </section>
         <section>
@@ -276,6 +279,9 @@ <h4 id="protectedproperty-signature">
             <code>
               protected readonly protectedProperty: TestEnum;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span><a href='./simple-suite-test#testenum-enum'>TestEnum</a></span></span>
+            </p>
           </section>
         </section>
       </section>

diff --git a/...st/snapshots/html/simple-suite-test/default-config/simple-suite-test/testclass-class.html b/...st/snapshots/html/simple-suite-test/default-config/simple-suite-test/testclass-class.html
@@ -463,6 +463,9 @@ <h4 id="testclasseventproperty-signature">
             <code>
               readonly testClassEventProperty: () =&gt; void;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>() =&gt; void</span></span>
+            </p>
           </section>
           <section>
             <h4 id="testclasseventproperty-remarks">
@@ -494,6 +497,9 @@ <h4 id="abstractpropertygetter-signature">
             <code>
               get abstractPropertyGetter(): TestMappedType;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span><a href='./simple-suite-test#testmappedtype-typealias'>TestMappedType</a></span></span>
+            </p>
           </section>
         </section>
         <section>
@@ -518,6 +524,9 @@ <h4 id="testclassgetterproperty-signature">
               <br>
               set testClassGetterProperty(newValue: number);
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>number</span></span>
+            </p>
           </section>
           <section>
             <h4 id="testclassgetterproperty-remarks">
@@ -544,6 +553,9 @@ <h4 id="testclassproperty-signature">
             <code>
               readonly testClassProperty: TTypeParameterB;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>TTypeParameterB</span></span>
+            </p>
           </section>
           <section>
             <h4 id="testclassproperty-remarks">
@@ -570,6 +582,9 @@ <h4 id="testclassstaticproperty-signature">
             <code>
               static testClassStaticProperty: (foo: number) =&gt; string;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>(foo: number) =&gt; string</span></span>
+            </p>
           </section>
         </section>
       </section>

diff --git a/...hots/html/simple-suite-test/default-config/simple-suite-test/testinterface-interface.html b/...hots/html/simple-suite-test/default-config/simple-suite-test/testinterface-interface.html
@@ -317,6 +317,9 @@ <h4 id="testclasseventproperty-signature">
             <code>
               readonly testClassEventProperty: () =&gt; void;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>() =&gt; void</span></span>
+            </p>
           </section>
           <section>
             <h4 id="testclasseventproperty-remarks">
@@ -348,6 +351,9 @@ <h4 id="getterproperty-signature">
             <code>
               get getterProperty(): boolean;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>boolean</span></span>
+            </p>
           </section>
         </section>
         <section>
@@ -370,6 +376,9 @@ <h4 id="setterproperty-signature">
               <br>
               set setterProperty(newValue: boolean);
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>boolean</span></span>
+            </p>
           </section>
         </section>
         <section>
@@ -388,6 +397,9 @@ <h4 id="testinterfaceproperty-signature">
             <code>
               testInterfaceProperty: number;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>number</span></span>
+            </p>
           </section>
           <section>
             <h4 id="testinterfaceproperty-remarks">
@@ -414,6 +426,9 @@ <h4 id="testoptionalinterfaceproperty-signature">
             <code>
               testOptionalInterfaceProperty?: number;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>number</span></span>
+            </p>
           </section>
         </section>
       </section>

diff --git a/...suite-test/default-config/simple-suite-test/testinterfacewithtypeparameter-interface.html b/...suite-test/default-config/simple-suite-test/testinterfacewithtypeparameter-interface.html
@@ -117,6 +117,9 @@ <h4 id="testproperty-signature">
             <code>
               testProperty: T;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>T</span></span>
+            </p>
           </section>
           <section>
             <h4 id="testproperty-remarks">

diff --git a/...tml/simple-suite-test/default-config/simple-suite-test/testnamespace/testclass-class.html b/...tml/simple-suite-test/default-config/simple-suite-test/testnamespace/testclass-class.html
@@ -202,6 +202,9 @@ <h4 id="testclassproperty-signature">
             <code>
               readonly testClassProperty: string;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>string</span></span>
+            </p>
           </section>
         </section>
       </section>

diff --git a/...le-suite-test/default-config/simple-suite-test/testnamespace/testinterface-interface.html b/...le-suite-test/default-config/simple-suite-test/testnamespace/testinterface-interface.html
@@ -134,6 +134,9 @@ <h4 id="testinterfaceproperty-signature">
             <code>
               testInterfaceProperty: boolean;
             </code>
+            <p>
+              <span><span><b>Type:</b> </span><span>boolean</span></span>
+            </p>
           </section>
         </section>
       </section>

diff --git a/...n-documenter/src/test/snapshots/html/simple-suite-test/flat-config/simple-suite-test.html b/...n-documenter/src/test/snapshots/html/simple-suite-test/flat-config/simple-suite-test.html
@@ -716,6 +716,9 @@ <h5 id="testclasseventproperty-signature">
               <code>
                 readonly testClassEventProperty: () =&gt; void;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span>() =&gt; void</span></span>
+              </p>
             </section>
             <section>
               <h5 id="testclasseventproperty-remarks">
@@ -747,6 +750,9 @@ <h5 id="getterproperty-signature">
               <code>
                 get getterProperty(): boolean;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span>boolean</span></span>
+              </p>
             </section>
           </section>
           <section>
@@ -769,6 +775,9 @@ <h5 id="setterproperty-signature">
                 <br>
                 set setterProperty(newValue: boolean);
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span>boolean</span></span>
+              </p>
             </section>
           </section>
           <section>
@@ -787,6 +796,9 @@ <h5 id="testinterfaceproperty-signature">
               <code>
                 testInterfaceProperty: number;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span>number</span></span>
+              </p>
             </section>
             <section>
               <h5 id="testinterfaceproperty-remarks">
@@ -813,6 +825,9 @@ <h5 id="testoptionalinterfaceproperty-signature">
               <code>
                 testOptionalInterfaceProperty?: number;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span>number</span></span>
+              </p>
             </section>
           </section>
         </section>
@@ -1254,6 +1269,9 @@ <h5 id="testproperty-signature">
               <code>
                 testProperty: T;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span>T</span></span>
+              </p>
             </section>
             <section>
               <h5 id="testproperty-remarks">
@@ -1519,6 +1537,9 @@ <h5 id="abstractpropertygetter-signature">
               <code>
                 abstract get abstractPropertyGetter(): TestMappedType;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span><a href='docs/simple-suite-test#testmappedtype-typealias'>TestMappedType</a></span></span>
+              </p>
             </section>
           </section>
           <section>
@@ -1537,6 +1558,9 @@ <h5 id="protectedproperty-signature">
               <code>
                 protected readonly protectedProperty: TestEnum;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span><a href='docs/simple-suite-test#testenum-enum'>TestEnum</a></span></span>
+              </p>
             </section>
           </section>
         </section>
@@ -2079,6 +2103,9 @@ <h5 id="testclasseventproperty-signature">
               <code>
                 readonly testClassEventProperty: () =&gt; void;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span>() =&gt; void</span></span>
+              </p>
             </section>
             <section>
               <h5 id="testclasseventproperty-remarks">
@@ -2110,6 +2137,9 @@ <h5 id="abstractpropertygetter-signature">
               <code>
                 get abstractPropertyGetter(): TestMappedType;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span><a href='docs/simple-suite-test#testmappedtype-typealias'>TestMappedType</a></span></span>
+              </p>
             </section>
           </section>
           <section>
@@ -2134,6 +2164,9 @@ <h5 id="testclassgetterproperty-signature">
                 <br>
                 set testClassGetterProperty(newValue: number);
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span>number</span></span>
+              </p>
             </section>
             <section>
               <h5 id="testclassgetterproperty-remarks">
@@ -2160,6 +2193,9 @@ <h5 id="testclassproperty-signature">
               <code>
                 readonly testClassProperty: TTypeParameterB;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span>TTypeParameterB</span></span>
+              </p>
             </section>
             <section>
               <h5 id="testclassproperty-remarks">
@@ -2186,6 +2222,9 @@ <h5 id="testclassstaticproperty-signature">
               <code>
                 static testClassStaticProperty: (foo: number) =&gt; string;
               </code>
+              <p>
+                <span><span><b>Type:</b> </span><span>(foo: number) =&gt; string</span></span>
+              </p>
             </section>
           </section>
         </section>
@@ -2805,6 +2844,9 @@ <h3 id="testconstwithemptydeprecatedblock-signature">
           <code>
             testConstWithEmptyDeprecatedBlock: string
           </code>
+          <p>
+            <span><span><b>Type:</b> </span><span>string</span></span>
+          </p>
         </section>
       </section>
     </section>
@@ -3310,6 +3352,9 @@ <h6 id="testnamespace-testclass-testclassproperty-property">
                   <code>
                     readonly testClassProperty: string;
                   </code>
+                  <p>
+                    <span><span><b>Type:</b> </span><span>string</span></span>
+                  </p>
                 </section>
               </section>
             </section>