refactor(compiler-cli): extract function overload separatly (angular#56489)

in order for the docs to process function entry, this commit refactor function extraction by keeping the implementation as a the default entry and adds all the overloads into a separate array of entries.

fixes angular#56144

PR Close angular#56489

Author: JeanMeche

packages/compiler-cli/src/ngtsc/docs/src/extractor.ts

@@ -154,7 +154,7 @@ export class DocsExtractor {
   private getExportedDeclarations(sourceFile: ts.SourceFile): DeclarationWithExportName[] {
     // Use the reflection host to get all the exported declarations from this
     // source file entry point.
-    const reflector = new TypeScriptReflectionHost(this.typeChecker);
+    const reflector = new TypeScriptReflectionHost(this.typeChecker, false, true);
     const exportedDeclarationMap = reflector.getExportsOfModule(sourceFile);
 
     // Augment each declaration with the exported name in the public API.

packages/compiler-cli/src/ngtsc/reflection/src/typescript.ts

@@ -31,9 +31,15 @@ import {isNamedClassDeclaration} from './util';
  */
 
 export class TypeScriptReflectionHost implements ReflectionHost {
+  /**
+   * @param skipPrivateValueDeclarationTypes Avoids using a value declaration that is considered private (using a ɵ-prefix),
+   * instead using the first available declaration. This is needed for the {@link FormControl} API of
+   * which the type declaration documents the type and the value declaration corresponds with an implementation detail.
+   */
   constructor(
     protected checker: ts.TypeChecker,
     private readonly isLocalCompilation = false,
+    private readonly skipPrivateValueDeclarationTypes = false,
   ) {}
 
   getDecoratorsOfDeclaration(declaration: DeclarationNode): Decorator[] | null {
@@ -398,9 +404,12 @@ export class TypeScriptReflectionHost implements ReflectionHost {
       symbol = this.checker.getAliasedSymbol(symbol);
     }
 
-    // Look at the resolved Symbol's declarations and pick one of them to return. Value declarations
-    // are given precedence over type declarations.
-    if (symbol.valueDeclaration !== undefined) {
+    // Look at the resolved Symbol's declarations and pick one of them to return.
+    // Value declarations are given precedence over type declarations if not specified otherwise
+    if (
+      symbol.valueDeclaration !== undefined &&
+      (!this.skipPrivateValueDeclarationTypes || !isPrivateSymbol(this.checker, symbol))
+    ) {
       return {
         node: symbol.valueDeclaration,
         viaModule: this._viaModule(symbol.valueDeclaration, originalId, importInfo),
@@ -781,6 +790,15 @@ function propertyNameToString(node: ts.PropertyName): string | null {
   }
 }
 
+/** Determines whether a given symbol represents a private API (symbols with names that start with `ɵ`) */
+function isPrivateSymbol(typeChecker: ts.TypeChecker, symbol: ts.Symbol) {
+  if (symbol.valueDeclaration !== undefined) {
+    const symbolType = typeChecker.getTypeOfSymbolAtLocation(symbol, symbol.valueDeclaration);
+    return symbolType?.symbol?.name.startsWith('ɵ') === true;
+  }
+  return false;
+}
+
 /**
  * Compute the left most identifier in a qualified type chain. E.g. the `a` of `a.b.c.SomeType`.
  * @param qualifiedName The starting property access expression from which we want to compute

packages/compiler-cli/test/ngtsc/doc_extraction/doc_extraction_filtering_spec.ts

@@ -45,5 +45,30 @@ runInEachFileSystem(() => {
       const docs: DocEntry[] = env.driveDocsExtraction('index.ts');
       expect(docs.length).toBe(0);
     });
+
+    it('should extract the type declaration if the value declaration is private', () => {
+      env.write(
+        'index.ts',
+        `
+       /**
+        * Documented 
+        */ 
+       export interface FormControl<T> {
+          name: string;
+       }
+       export interface ɵFormControlCtor {
+        new (): FormControl<any>;
+       }
+       export const FormControl: ɵFormControlCtor = class FormControl<TValue = any> {
+       
+       }
+      `,
+      );
+
+      const docs: DocEntry[] = env.driveDocsExtraction('index.ts');
+      expect(docs.length).toBe(1);
+      expect(docs[0].name).toBe('FormControl');
+      expect(docs[0].rawComment).toMatch(/Documented/);
+    });
   });
 });