refactor(api-gen): add support for function overloads (#2020)

PR Close #2020

bazel/api-gen/rendering/entities.ts

@@ -139,6 +139,10 @@ export interface FunctionEntry extends DocEntry {
  isNewType: boolean;
 }
 
+export interface FunctionWithOverloadsEntry extends FunctionEntry {
+ overloads: FunctionEntry[] | null;
+}
+
 /** Sub-entry for a single class or enum member. */
 export interface MemberEntry {
  name: string;
@@ -200,3 +204,7 @@ export interface InitializerApiFunctionEntry extends DocEntry {
 export function isDocEntryWithSourceInfo(entry: DocEntry): entry is DocEntryWithSourceInfo {
  return 'source' in entry;
 }
+
+export function isFunctionEntryWithOverloads(entry: DocEntry): entry is FunctionWithOverloadsEntry {
+ return 'overloads' in entry;
+}

bazel/api-gen/rendering/entities/renderables.ts

@@ -75,6 +75,7 @@ export type FunctionEntryRenderable = FunctionEntry &
  codeLinesGroups: Map<string, CodeLineRenderable[]>;
  params: ParameterEntryRenderable[];
  deprecationMessage: string | null;
+ overloads: FunctionEntryRenderable[] | null;
  };
 
 /** Sub-entry for a single class or enum member augmented with transformed content for rendering. */

bazel/api-gen/rendering/entities/traits.ts

@@ -1,7 +1,8 @@
-import {JsDocTagEntry, MemberEntry, ParameterEntry} from '../entities';
+import {FunctionEntry, JsDocTagEntry, MemberEntry, ParameterEntry} from '../entities';
 
 import {
  CodeLineRenderable,
+ FunctionEntryRenderable,
  JsDocTagRenderable,
  LinkEntryRenderable,
  MemberEntryRenderable,
@@ -78,6 +79,14 @@ export interface HasRenderableParams {
  params: ParameterEntryRenderable[];
 }
 
+export interface HasOverloads {
+ overloads: FunctionEntry[] | null;
+}
+
+export interface HasRenderableOverloads {
+ overloads: FunctionEntryRenderable[] | null;
+}
+
 export interface HasDeprecatedFlag {
  isDeprecated: boolean;
  deprecationMessage: string | null;

bazel/api-gen/rendering/templates/deprecated-label.tsx

@@ -21,7 +21,7 @@ export function DeprecatedLabel(props: {
  <span dangerouslySetInnerHTML={{__html: entry.deprecationMessage}}></span>
  </div>
  );
- } else if ('isDeprecated' in entry) {
+ } else if ('isDeprecated' in entry && entry.isDeprecated) {
  return <span className={`${PARAM_KEYWORD_CLASS_NAME} docs-deprecated`}>@deprecated</span>;
  }
 

bazel/api-gen/rendering/templates/function-reference.tsx

@@ -45,7 +45,11 @@ export function FunctionReference(entry: FunctionEntryRenderable) {
  )}
  </header>
  <div className={REFERENCE_MEMBER_CARD_BODY}>
- <ClassMethodInfo entry={entry} />
+ {entry.overloads ? (
+ entry.overloads.map((overload) => <ClassMethodInfo entry={overload} />)
+ ) : (
+ <ClassMethodInfo entry={entry} isOverloaded={true} />
+ )}
  </div>
  </div>
  </div>

bazel/api-gen/rendering/transforms/code-transforms.ts

@@ -6,15 +6,16 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import highlightJs from 'highlight.js';
 import {
  DocEntry,
  FunctionEntry,
  MemberEntry,
  MemberTags,
  ParameterEntry,
  PropertyEntry,
+ isFunctionEntryWithOverloads,
 } from '../entities';
-import highlightJs from 'highlight.js';
 
 import {
  isClassEntry,
@@ -126,10 +127,33 @@ export function mapDocEntryToCode(entry: DocEntry): CodeTableOfContentsData {
 
  if (isFunctionEntry(entry)) {
  const isDeprecated = isDeprecatedEntry(entry);
+ const codeLineNumbersWithIdentifiers = new Map<number, string>();
 
+ if (isFunctionEntryWithOverloads(entry) && entry.overloads) {
+ const initialMetadata: CodeTableOfContentsData = {
+ contents: '',
+ codeLineNumbersWithIdentifiers: new Map<number, string>(),
+ deprecatedLineNumbers: [],
+ };
+
+ return entry.overloads.reduce(
+ (acc: CodeTableOfContentsData, curr: FunctionEntry, index: number) => {
+ const lineNumber = index;
+ acc.codeLineNumbersWithIdentifiers.set(lineNumber, curr.name);
+ acc.contents += `${curr.name}.${curr.params
+ .map((param) => mapParamEntry(param))
+ .join(`, `)}: ${curr.returnType}\n`;
+ if (isDeprecatedEntry(curr)) {
+ acc.deprecatedLineNumbers.push(lineNumber);
+ }
+ return acc;
+ },
+ initialMetadata,
+ );
+ }
  return {
  contents: getMethodCodeLine(entry, [], true),
- codeLineNumbersWithIdentifiers: new Map(),
+ codeLineNumbersWithIdentifiers,
  deprecatedLineNumbers: isDeprecated ? [0] : [],
  };
  }
@@ -254,19 +278,19 @@ function getMethodCodeLine(
  memberTags: MemberTags[] = [],
  displayParamsInNewLines: boolean = false,
 ): string {
- const mapParamEntry = (entry: ParameterEntry): string => {
- return `${entry.isRestParam ? '...' : ''}${entry.name}${markOptional(entry.isOptional)}: ${
- entry.type
- }`;
- };
-
  return `${memberTags.join(' ')} ${member.name}(${displayParamsInNewLines ? '\n ' : ''}${member.params
  .map((param) => mapParamEntry(param))
  .join(`,${displayParamsInNewLines ? '\n ' : ' '}`)}${
  displayParamsInNewLines ? '\n' : ''
  }): ${member.returnType};`.trim();
 }
 
+function mapParamEntry(entry: ParameterEntry) {
+ return `${entry.isRestParam ? '...' : ''}${entry.name}${markOptional(entry.isOptional)}: ${
+ entry.type
+ }`;
+}
+
 function getGetterCodeLine(member: PropertyEntry): string {
  const tags = getTags(member);
 

bazel/api-gen/rendering/transforms/function-transforms.ts

@@ -6,8 +6,9 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {FunctionEntry} from '../entities';
+import {FunctionEntry, isFunctionEntryWithOverloads} from '../entities';
 import {FunctionEntryRenderable} from '../entities/renderables';
+import {HasRenderableOverloads} from '../entities/traits';
 import {addRenderableCodeToc} from './code-transforms';
 import {
  addHtmlAdditionalLinks,
@@ -27,12 +28,30 @@ export function getFunctionRenderable(
  return setEntryFlags(
  addRenderableCodeToc(
  addRenderableFunctionParams(
- addHtmlAdditionalLinks(
- addHtmlUsageNotes(
- addHtmlJsDocTagComments(addHtmlDescription(addModuleName(entry, moduleName))),
+ addOverloads(
+ moduleName,
+ addHtmlAdditionalLinks(
+ addHtmlUsageNotes(
+ setEntryFlags(
+ addHtmlJsDocTagComments(addHtmlDescription(addModuleName(entry, moduleName))),
+ ),
+ ),
  ),
  ),
  ),
  ),
  );
 }
+
+function addOverloads<T extends FunctionEntry>(
+ moduleName: string,
+ entry: T,
+): T & HasRenderableOverloads {
+ return {
+ ...entry,
+ overloads:
+ isFunctionEntryWithOverloads(entry) && entry.overloads
+ ? entry.overloads.map((overload) => getFunctionRenderable(overload, moduleName))
+ : null,
+ };
+}