refactor(core): add dedicated deprecated signatures for providedIn: any / NgModule.

Those were deprecated by #47616 back in v15.

fixes #65923

(cherry picked from commit 8199945)

Author: JeanMeche

adev/shared-docs/pipeline/api-gen/rendering/entities/categorization.mts

@@ -174,8 +174,9 @@ function getTag<T extends HasJsDocTags | FunctionEntry>(entry: T, tag: string, e
 export function getTagSinceVersion<T extends HasJsDocTags>(
   entry: T,
   tagName: string,
+  every = false,
 ): {version: string | undefined} | undefined {
-  const tag = getTag(entry, tagName);
+  const tag = getTag(entry, tagName, every);
   if (!tag) {
     return undefined;
   }

adev/shared-docs/pipeline/api-gen/rendering/test/transforms/jsdoc-transforms.spec.mts

@@ -9,7 +9,11 @@
 import {initHighlighter} from '../../../../shared/shiki.mjs';
 import {setHighlighterInstance} from '../../shiki/shiki.mjs';
 import {setCurrentSymbol, setSymbols} from '../../symbol-context.mjs';
-import {addHtmlAdditionalLinks, addHtmlDescription} from '../../transforms/jsdoc-transforms.mjs';
+import {
+  addHtmlAdditionalLinks,
+  addHtmlDescription,
+  setEntryFlags,
+} from '../../transforms/jsdoc-transforms.mjs';
 
 // @ts-ignore This compiles fine, but Webstorm doesn't like the ESM import in a CJS context.
 describe('jsdoc transforms', () => {
@@ -230,4 +234,62 @@ function setupRouter() {
 
     expect(entry.htmlDescription).toContain('/api/angular/router/Router');
   });
+
+  it('should only mark as deprecated if all overloads are deprecated', () => {
+    const entry = setEntryFlags({
+      name: 'Injectable',
+      jsdocTags: [
+        {'name': 'see', 'comment': '[Introduction to Services and DI](guide/di)'},
+        {
+          'name': 'see',
+          'comment': '[Creating and using services](guide/di/creating-and-using-services)',
+        },
+      ],
+      signatures: [
+        {
+          'parameters': [],
+          'jsdocTags': [{'name': 'see', 'comment': '[Introduction to Services and DI](guide/di)'}],
+        },
+        {
+          'parameters': [],
+          'jsdocTags': [
+            {
+              'name': 'deprecated',
+              'comment':
+                "The `providedIn: NgModule` or `providedIn:'any'` options are deprecated. Please use the other signatures.",
+            },
+          ],
+        },
+      ],
+    } as any);
+
+    expect(entry.deprecated).toEqual(undefined);
+
+    const deprecatedEntry = setEntryFlags({
+      name: 'Injectable',
+      jsdocTags: [
+        {'name': 'see', 'comment': '[Introduction to Services and DI](guide/di)'},
+        {
+          'name': 'see',
+          'comment': '[Creating and using services](guide/di/creating-and-using-services)',
+        },
+      ],
+      signatures: [
+        {
+          'parameters': [],
+          'jsdocTags': [
+            {'name': 'see', 'comment': '[Introduction to Services and DI](guide/di)'},
+            {'name': 'deprecated', 'comment': '19.0 something something'},
+          ],
+        },
+        {
+          'parameters': [],
+          'jsdocTags': [{'name': 'deprecated', 'comment': '19.0 something something'}],
+        },
+      ],
+    } as any);
+
+    // It's deprecated by
+    expect(deprecatedEntry.deprecated).toEqual({version: '19.0'});
+  });
 });

adev/shared-docs/pipeline/api-gen/rendering/transforms/jsdoc-transforms.mts

@@ -119,7 +119,7 @@ export function setEntryFlags<T extends HasJsDocTags & HasModuleName>(
   const deprecationMessage = getDeprecatedEntry(entry);
   return {
     ...entry,
-    deprecated: getTagSinceVersion(entry, 'deprecated'),
+    deprecated: getTagSinceVersion(entry, 'deprecated', true),
     deprecationMessage: deprecationMessage
       ? getHtmlForJsDocText(deprecationMessage)
       : deprecationMessage,

goldens/public-api/core/index.api.md

@@ -884,9 +884,13 @@ export const Injectable: InjectableDecorator;
 // @public
 export interface InjectableDecorator {
     (): TypeDecorator;
+    // @deprecated (undocumented)
+    (options?: {
+        providedIn: Type<any> | 'any';
+    } & InjectableProvider): TypeDecorator;
     // (undocumented)
     (options?: {
-        providedIn: Type<any> | 'root' | 'platform' | 'any' | null;
+        providedIn: 'root' | 'platform' | null;
     } & InjectableProvider): TypeDecorator;
     // (undocumented)
     new (): Injectable;
@@ -916,6 +920,11 @@ export interface InjectDecorator {
 
 // @public
 export class InjectionToken<T> {
+    // @deprecated
+    constructor(_desc: string, options: {
+        providedIn?: Type<any> | 'any';
+        factory: () => T;
+    });
     constructor(_desc: string, options?: {
         providedIn?: Type<any> | 'root' | 'platform' | 'any' | null;
         factory: () => T;

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

@@ -202,13 +202,18 @@ function getDecoratorJsDocNode(
   const decoratorInterface = getDecoratorInterface(declaration, typeChecker);
 
   // The public-facing JsDoc for each decorator is on one of its interface's call signatures.
-  const callSignature = decoratorInterface.members
-    .filter((node) => {
+  const callSignaturesWithJsDoc = decoratorInterface.members.filter(
+    (node): node is ts.CallSignatureDeclaration => {
       // The description block lives on one of the call signatures for this interface.
-      return ts.isCallSignatureDeclaration(node) && extractRawJsDoc(node);
-    })
-    .at(-1); // Get the last one, as it is the most complete
-
+      return ts.isCallSignatureDeclaration(node) && !!extractRawJsDoc(node);
+    },
+  );
+
+  // There may be multiple call signatures, so we need to find the one with the
+  // longest JSDoc block. This is the one that is intended for public consumption.
+  const callSignature = callSignaturesWithJsDoc.sort(
+    (a, b) => (extractRawJsDoc(b)?.length ?? 0) - (extractRawJsDoc(a)?.length ?? 0),
+  )[0];
   if (!callSignature || !ts.isCallSignatureDeclaration(callSignature)) {
     throw new Error(`No call signature with JsDoc on "${name}Decorator"`);
   }

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

@@ -177,5 +177,51 @@ runInEachFileSystem(() => {
       expect(param1.type).toBe('string');
       expect(param1.description).toBe('');
     });
+
+    it('should extract the decorator with some deprecated signatures', () => {
+      env.write(
+        'index.ts',
+        `
+        export interface InjectableDecorator {
+          /**
+           * Decorator that marks a class as available to be
+           * provided and injected as a dependency.
+           *
+           * @usageNotes
+           *
+           * Some usage.... 
+           */
+          (): TypeDecorator;
+          /**
+           * @deprecated deprecated.
+           */
+          (options?: {providedIn: Type<any> | 'any'} & InjectableProvider): TypeDecorator;
+          (
+            options?: {providedIn: Type<any> | 'root' | 'platform' | 'any' | null} & InjectableProvider,
+          ): TypeDecorator;
+          new (): Injectable;
+          new (
+            options?: {providedIn: Type<any> | 'root' | 'platform' | 'any' | null} & InjectableProvider,
+          ): Injectable;
+        }
+
+        export interface Injectable {
+          providedIn?: Type<any> | 'root' | 'platform' | 'any' | null;
+        }
+
+        function makePropDecorator(): InjectDecorator { return () => {}; }
+        export const Injectable: InjectableDecorator = makeDecorator('Injectable', undefined, undefined, undefined,(type: Type<any>, meta: Injectable) => ({} as any),
+        );
+        `,
+      );
+
+      const docs: DocEntry[] = env.driveDocsExtraction('index.ts');
+      expect(docs.length).toBe(1);
+
+      expect(docs[0].name).toBe('Injectable');
+      expect(docs[0].description).toContain('Decorator that marks a class');
+      expect(docs[0].entryType).toBe(EntryType.Decorator);
+      expect(docs[0].jsdocTags[0]).toBeDefined();
+    });
   });
 });

packages/core/src/di/injectable.ts

@@ -61,9 +61,12 @@ export interface InjectableDecorator {
    *
    */
   (): TypeDecorator;
-  (
-    options?: {providedIn: Type<any> | 'root' | 'platform' | 'any' | null} & InjectableProvider,
-  ): TypeDecorator;
+
+  /**
+   * @deprecated The `providedIn: NgModule` or `providedIn:'any'` options are deprecated. Please use the other signatures.
+   */
+  (options?: {providedIn: Type<any> | 'any'} & InjectableProvider): TypeDecorator;
+  (options?: {providedIn: 'root' | 'platform' | null} & InjectableProvider): TypeDecorator;
   new (): Injectable;
   new (
     options?: {providedIn: Type<any> | 'root' | 'platform' | 'any' | null} & InjectableProvider,

packages/core/src/di/injection_token.ts

@@ -68,12 +68,31 @@ export class InjectionToken<T> {
 
   readonly ɵprov: unknown;
 
+  /**
+   * @deprecated The `providedIn: NgModule` or `providedIn:'any'` options are deprecated. Please use the other signature.
+   */
+  constructor(
+    _desc: string,
+    options: {
+      providedIn?: Type<any> | 'any';
+      factory: () => T;
+    },
+  );
+
   /**
    * @param _desc   Description for the token,
    *                used only for debugging purposes,
    *                it should but does not need to be unique
    * @param options Options for the token's usage, as described above
    */
+  constructor(
+    _desc: string,
+    options?: {
+      providedIn?: Type<any> | 'root' | 'platform' | 'any' | null;
+      factory: () => T;
+    },
+  );
+
   constructor(
     protected _desc: string,
     options?: {