docs(docs-infra): update default generic values and add constraints for type parameters in functions (#58548)

alan-agius4 · thePunderWoman · commit 9199dd9a8702 · 2024-11-08T17:15:07.000Z
Before ```typescript createNodeRequestHandler( handler: T ): T; ``` ```typescript class NgIf<T> { @input() set ngIf(value: T); @input() set ngIfThen(value: TemplateRef<NgIfContext<T>> | null); @input() set ngIfElse(value: TemplateRef<NgIfContext<T>> | null); static ngTemplateGuard_ngIf: "binding"; static ngTemplateContextGuard<T>(dir: NgIf<T>, ctx: any): boolean; } ``` Now ```typescript createNodeRequestHandler<T extends NodeRequestHandlerFunction>( handler: T ): T; ``` ```typescript class NgIf<T = unknown> { @input() set ngIf(value: T); @input() set ngIfThen(value: TemplateRef<NgIfContext<T>> | null); @input() set ngIfElse(value: TemplateRef<NgIfContext<T>> | null); static ngTemplateGuard_ngIf: "binding"; static ngTemplateContextGuard<T>(dir: NgIf<T>, ctx: any): boolean; } ``` PR Close #58548
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/test/transforms/code-transforms.spec.ts b/adev/shared-docs/pipeline/api-gen/rendering/test/transforms/code-transforms.spec.ts
@@ -0,0 +1,59 @@
+import {makeGenericsText} from '../../transforms/code-transforms';
+
+describe('makeGenericsText', () => {
+  it('should return an empty string if no generics are provided', () => {
+    expect(makeGenericsText(undefined)).toBe('');
+    expect(makeGenericsText([])).toBe('');
+  });
+
+  it('should return a single generic type without constraints or default', () => {
+    const generics = [{name: 'T', constraint: undefined, default: undefined}];
+    expect(makeGenericsText(generics)).toBe('<T>');
+  });
+
+  it('should handle a single generic type with a constraint', () => {
+    const generics = [{name: 'T', constraint: 'string', default: undefined}];
+    expect(makeGenericsText(generics)).toBe('<T extends string>');
+  });
+
+  it('should handle a single generic type with a default value', () => {
+    const generics = [{name: 'T', default: 'number', constraint: undefined}];
+    expect(makeGenericsText(generics)).toBe('<T = number>');
+  });
+
+  it('should handle a single generic type with both constraint and default value', () => {
+    const generics = [{name: 'T', constraint: 'string', default: 'number'}];
+    expect(makeGenericsText(generics)).toBe('<T extends string = number>');
+  });
+
+  it('should handle multiple generic types without constraints or defaults', () => {
+    const generics = [
+      {name: 'T', constraint: undefined, default: undefined},
+      {name: 'U', constraint: undefined, default: undefined},
+    ];
+    expect(makeGenericsText(generics)).toBe('<T, U>');
+  });
+
+  it('should handle multiple generic types with constraints and defaults', () => {
+    const generics = [
+      {name: 'T', constraint: 'string', default: 'number'},
+      {name: 'U', constraint: 'boolean', default: undefined},
+      {name: 'V', default: 'any', constraint: undefined},
+    ];
+    expect(makeGenericsText(generics)).toBe(
+      '<T extends string = number, U extends boolean, V = any>',
+    );
+  });
+
+  it('should handle complex generics with mixed constraints and defaults', () => {
+    const generics = [
+      {name: 'A', constraint: 'string', default: undefined},
+      {name: 'B', constraint: undefined, default: undefined},
+      {name: 'C', default: 'number', constraint: undefined},
+      {name: 'D', constraint: 'boolean', default: 'true'},
+    ];
+    expect(makeGenericsText(generics)).toBe(
+      '<A extends string, B, C = number, D extends boolean = true>',
+    );
+  });
+});
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/transforms/code-transforms.ts b/adev/shared-docs/pipeline/api-gen/rendering/transforms/code-transforms.ts
@@ -9,6 +9,7 @@
 import {
   DocEntry,
   FunctionSignatureMetadata,
+  GenericEntry,
   MemberEntry,
   MemberTags,
   ParameterEntry,
@@ -332,8 +333,10 @@ function getMethodCodeLine(
   displayParamsInNewLines: boolean = false,
   isFunction: boolean = false,
 ): string {
+  const generics = makeGenericsText(member.generics);
+
   displayParamsInNewLines &&= member.params.length > 0;
-  return `${isFunction ? 'function' : ''}${memberTags.join(' ')} ${member.name}(${displayParamsInNewLines ? '\n  ' : ''}${member.params
+  return `${isFunction ? 'function' : ''}${memberTags.join(' ')} ${member.name}${generics}(${displayParamsInNewLines ? '\n  ' : ''}${member.params
     .map((param) => mapParamEntry(param))
     .join(`,${displayParamsInNewLines ? '\n  ' : ' '}`)}${
     displayParamsInNewLines ? '\n' : ''
@@ -442,12 +445,7 @@ function appendPrefixAndSuffix(entry: DocEntry, codeTocData: CodeTableOfContents
   };
 
   if (isClassEntry(entry) || isInterfaceEntry(entry)) {
-    const generics =
-      entry.generics?.length > 0
-        ? `<${entry.generics
-            .map((g) => (g.constraint ? `${g.name} extends ${g.constraint}` : g.name))
-            .join(', ')}>`
-        : '';
+    const generics = makeGenericsText(entry.generics);
 
     const extendsStr = entry.extends ? ` extends ${entry.extends}` : '';
     // TODO: remove the ? when we distinguish Class & Decorator entries
@@ -501,3 +499,45 @@ export function addApiLinksToHtml(htmlString: string): string {
 
   return result;
 }
+
+/**
+ * Constructs a TypeScript generics string based on an array of generic type entries.
+ *
+ * This function takes an array of generic type entries and returns a formatted string
+ * representing TypeScript generics syntax, including any constraints and default values
+ * specified in each entry.
+ *
+ * @param generics - An array of `GenericEntry` objects representing the generics to be formatted,
+ *                   or `undefined` if there are no generics.
+ *
+ * @returns A formatted string representing TypeScript generics syntax, or an empty string if no generics are provided.
+ */
+export function makeGenericsText(generics: GenericEntry[] | undefined): string {
+  if (!generics?.length) {
+    return '';
+  }
+
+  const parts: string[] = ['<'];
+
+  for (let index = 0; index < generics.length; index++) {
+    const {constraint, default: defaultVal, name} = generics[index];
+
+    parts.push(name);
+
+    if (constraint) {
+      parts.push(' extends ', constraint);
+    }
+
+    if (defaultVal !== undefined) {
+      parts.push(' = ', defaultVal);
+    }
+
+    if (index < generics.length - 1) {
+      parts.push(', ');
+    }
+  }
+
+  parts.push('>');
+
+  return parts.join('');
+}
