refactor(compiler-cli): add the ability to treat object literals as enums in docs (#54487)

crisbeto · alxhub · commit f00336c31f94 · 2024-02-21T15:21:59.000-08:00
We have a couple of cases now (#53753 and #54414) where we're forced to redefine enums as object literals. These literals aren't rendered in the best way in the docs so these changes introduce a new `object-literal-as-enum` tag that we can use to mark them so they're treated for documentation purposes. PR Close #54487
diff --git a/packages/compiler-cli/src/ngtsc/docs/src/constant_extractor.ts b/packages/compiler-cli/src/ngtsc/docs/src/constant_extractor.ts
@@ -8,12 +8,15 @@
 
 import ts from 'typescript';
 
-import {ConstantEntry, EntryType} from './entities';
-import {extractJsDocDescription, extractJsDocTags, extractRawJsDoc,} from './jsdoc_extractor';
+import {ConstantEntry, EntryType, EnumEntry, EnumMemberEntry, MemberType} from './entities';
+import {extractJsDocDescription, extractJsDocTags, extractRawJsDoc} from './jsdoc_extractor';
+
+/** Name of the tag indicating that an object literal should be shown as an enum in docs. */
+const LITERAL_AS_ENUM_TAG = 'object-literal-as-enum';
 
 /** Extracts documentation entry for a constant. */
 export function extractConstant(
-    declaration: ts.VariableDeclaration, typeChecker: ts.TypeChecker): ConstantEntry {
+    declaration: ts.VariableDeclaration, typeChecker: ts.TypeChecker): ConstantEntry|EnumEntry {
   // For constants specifically, we want to get the base type for any literal types.
   // For example, TypeScript by default extracts `const PI = 3.14` as PI having a type of the
   // literal `3.14`. We don't want this behavior for constants, since generally one wants the
@@ -26,20 +29,71 @@ export function extractConstant(
   // In the TS AST, the leading comment for a variable declaration is actually
   // on the ancestor `ts.VariableStatement` (since a single variable statement may
   // contain multiple variable declarations).
-  const variableStatement = declaration.parent.parent;
   const rawComment = extractRawJsDoc(declaration.parent.parent);
+  const jsdocTags = extractJsDocTags(declaration);
+  const description = extractJsDocDescription(declaration);
+  const name = declaration.name.getText();
+
+  // Some constants have to be treated as enums for documentation purposes.
+  if (jsdocTags.some(tag => tag.name === LITERAL_AS_ENUM_TAG)) {
+    return {
+      name,
+      entryType: EntryType.Enum,
+      members: extractLiteralPropertiesAsEnumMembers(declaration),
+      rawComment,
+      description,
+      jsdocTags: jsdocTags.filter(tag => tag.name !== LITERAL_AS_ENUM_TAG),
+    };
+  }
 
   return {
-    name: declaration.name.getText(),
+    name: name,
     type: typeChecker.typeToString(resolvedType),
     entryType: EntryType.Constant,
     rawComment,
-    description: extractJsDocDescription(declaration),
-    jsdocTags: extractJsDocTags(declaration),
+    description,
+    jsdocTags,
   };
 }
 
 /** Gets whether a given constant is an Angular-added const that should be ignored for docs. */
 export function isSyntheticAngularConstant(declaration: ts.VariableDeclaration) {
   return declaration.name.getText() === 'USED_FOR_NG_TYPE_CHECKING';
 }
+
+
+/**
+ * Extracts the properties of a variable initialized as an object literal as if they were enum
+ * members. Will throw for any variables that can't be statically analyzed easily.
+ */
+function extractLiteralPropertiesAsEnumMembers(declaration: ts.VariableDeclaration):
+    EnumMemberEntry[] {
+  const initializer = declaration.initializer;
+
+  if (initializer === undefined || !ts.isObjectLiteralExpression(initializer)) {
+    throw new Error(`Declaration tagged with "${
+        LITERAL_AS_ENUM_TAG}" must be initialized to an object literal`);
+  }
+
+  return initializer.properties.map(prop => {
+    if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) {
+      throw new Error(`Property in declaration tagged with "${
+          LITERAL_AS_ENUM_TAG}" must be a property assignment with a static name`);
+    }
+
+    if (!ts.isNumericLiteral(prop.initializer) && !ts.isStringLiteralLike(prop.initializer)) {
+      throw new Error(`Property in declaration tagged with "${
+          LITERAL_AS_ENUM_TAG}" must be initialized to a number or string literal`);
+    }
+
+    return ({
+      name: prop.name.text,
+      type: `${declaration.name.getText()}.${prop.name.text}`,
+      value: prop.initializer.getText(),
+      memberType: MemberType.EnumItem,
+      jsdocTags: extractJsDocTags(prop),
+      description: extractJsDocDescription(prop),
+      memberTags: [],
+    });
+  });
+}
diff --git a/packages/compiler-cli/test/ngtsc/doc_extraction/constant_doc_extraction_spec.ts b/packages/compiler-cli/test/ngtsc/doc_extraction/constant_doc_extraction_spec.ts
@@ -7,7 +7,7 @@
  */
 
 import {DocEntry} from '@angular/compiler-cli/src/ngtsc/docs';
-import {ConstantEntry, EntryType} from '@angular/compiler-cli/src/ngtsc/docs/src/entities';
+import {ConstantEntry, EntryType, EnumEntry} from '@angular/compiler-cli/src/ngtsc/docs/src/entities';
 import {runInEachFileSystem} from '@angular/compiler-cli/src/ngtsc/file_system/testing';
 import {loadStandardTestFiles} from '@angular/compiler-cli/src/ngtsc/testing';
 
@@ -77,5 +77,43 @@ runInEachFileSystem(() => {
       expect(typedToken.entryType).toBe(EntryType.Constant);
       expect(typedToken.type).toBe('InjectionToken<string>');
     });
+
+    it('should extract an object literal marked as an enum', () => {
+      env.write('index.ts', `
+        /**
+         * Toppings for your pizza.
+         * @object-literal-as-enum
+         */
+        export const PizzaTopping = {
+          /** It is cheese */
+          Cheese: 0,
+
+          /** Or "tomato" if you are British */
+          Tomato: "tomato",
+        }
+      `);
+
+      const docs: DocEntry[] = env.driveDocsExtraction('index.ts');
+
+      expect(docs.length).toBe(1);
+      expect(docs[0].entryType).toBe(EntryType.Enum);
+      expect(docs[0].jsdocTags).toEqual([]);
+
+      const enumEntry = docs[0] as EnumEntry;
+      expect(enumEntry.name).toBe('PizzaTopping');
+      expect(enumEntry.members.length).toBe(2);
+
+      const [cheeseEntry, tomatoEntry] = enumEntry.members;
+
+      expect(cheeseEntry.name).toBe('Cheese');
+      expect(cheeseEntry.description).toBe('It is cheese');
+      expect(cheeseEntry.value).toBe('0');
+      expect(cheeseEntry.type).toBe('PizzaTopping.Cheese');
+
+      expect(tomatoEntry.name).toBe('Tomato');
+      expect(tomatoEntry.description).toBe('Or "tomato" if you are British');
+      expect(tomatoEntry.value).toBe('"tomato"');
+      expect(tomatoEntry.type).toBe('PizzaTopping.Tomato');
+    });
   });
 });
