Closes Azure/typespec-azure-pr#3107

Azure · Apr 19, 2024 · 59aadf1 · 59aadf1
1 parent 84c1ca9
commit 59aadf1
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 7 deletions.
diff --git a/packages/typespec-azure-core/src/rules/require-docs.ts b/packages/typespec-azure-core/src/rules/require-docs.ts
@@ -3,6 +3,7 @@ import {
   Model,
   Operation,
   Program,
+  Union,
   createRule,
   getDiscriminatedTypes,
   getDoc,
@@ -33,8 +34,25 @@ function isExcludedEnumType(program: Program, enumObj: Enum): boolean {
         return true;
       }
     } else if (type.kind === "Union") {
-      // TODO: handle union types
-      let test = "best";
+      const discriminatorVariant = type.variants.get(discName.propertyName);
+      if (discriminatorVariant?.type === enumObj) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/** Discriminator unions are self-documenting and don't need separate documentation. */
+function isExcludedUnionType(program: Program, union: Union): boolean {
+  const discTypes = getDiscriminatedTypes(program);
+  for (const [type, discName] of discTypes) {
+    // FIXME: Detect when union is a discriminator
+    if (type.kind === "Union") {
+      const discriminatorVariant = type.variants.get(discName.propertyName);
+      if (discriminatorVariant?.type === union) {
+        return true;
+      }
     }
   }
   return false;
@@ -119,6 +137,9 @@ export const requireDocumentation = createRule({
             ) {
               return;
             }
+            if (prop.type.kind === "Union" && isExcludedUnionType(context.program, prop.type)) {
+              return;
+            }
             if (!getDoc(context.program, prop)) {
               context.reportDiagnostic({
                 target: prop,

diff --git a/packages/typespec-azure-core/test/rules/require-docs.test.ts b/packages/typespec-azure-core/test/rules/require-docs.test.ts
@@ -120,14 +120,20 @@ describe("typespec-azure-core: documentation-required rule", () => {
       await tester
         .expect(
           `
+          union PetKind {
+            cat: "cat",
+            string,
+          }
+          
           @discriminator("kind")
-          union Pet {
-            cat: Cat,
+          @doc("Base Pet model")
+          model Pet {
+            kind: PetKind;
           }
           
-          @doc("A Cat!")
-          model Cat {
-            kind: "cat";
+          @doc("A Merry Ol' Cat")
+          model Cat extends Pet {
+            kind: PetKind.cat,
           }`
         )
         .toBeValid();