Yuchao Yan (msyyc) · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026 · Oct 12, 2026 · Oct 14, 2026
@@ -0,0 +1,13 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-azure-core"
+---
+
+Strengthen `documentation-required` to reject explicitly empty or whitespace-only documentation and descriptions that repeat a declaration's name or the placeholder `description`. Ordinary properties use their authored names, regardless of JSON serialization names; HTTP parameters and multipart parts retain their HTTP names. Explicit-documentation checks also cover namespaces, interfaces, scalars, inline properties, union variants, and declarations exempt from missing-doc requirements when their documentation is exposed by the compiler. Operation descriptions are compared with both the source operation name and effective HTTP verb. Missing-documentation requirements and exemptions are unchanged. The existing data-plane and resource-manager rulesets already enable this rule.
+
+```tsp
+// Warns: the description only repeats the authored name.
+/** Widget */
+model Widget {}
+```
@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@azure-tools/typespec-samples"
+---
+
+Update Widget Manager color and ARM library provisioning-state descriptions to satisfy documentation-required, and regenerate sample snapshots.
@@ -39,19 +39,19 @@ enum Versions {
 union WidgetColor {
   string,
 
-  @doc("Black")
+  @doc("The widget is black.")
   Black: "Black",
 
-  @doc("White")
+  @doc("The widget is white.")
   White: "White",
 
-  @doc("Red")
+  @doc("The widget is red.")
   Red: "Red",
 
-  @doc("Green")
+  @doc("The widget is green.")
   Green: "Green",
 
-  @doc("Blue")
+  @doc("The widget is blue.")
   Blue: "Blue",
 }
 

@@ -75,7 +75,7 @@ union SystemEnvelopeProvisioningState {
   string,
   ResourceProvisioningState,
 
-  @doc("Working")
+  @doc("The resource provisioning operation is in progress.")
   Working: "Working",
 }
 

@@ -2249,27 +2249,27 @@
           {
             "name": "Black",
             "value": "Black",
-            "description": "Black"
+            "description": "The widget is black."
           },
           {
             "name": "White",
             "value": "White",
-            "description": "White"
+            "description": "The widget is white."
           },
           {
             "name": "Red",
             "value": "Red",
-            "description": "Red"
+            "description": "The widget is red."
           },
           {
             "name": "Green",
             "value": "Green",
-            "description": "Green"
+            "description": "The widget is green."
           },
           {
             "name": "Blue",
             "value": "Blue",
-            "description": "Blue"
+            "description": "The widget is blue."
           }
         ]
       }

@@ -1982,7 +1982,7 @@
           {
             "name": "Working",
             "value": "Working",
-            "description": "Working"
+            "description": "The resource provisioning operation is in progress."
           }
         ]
       },

@@ -58,7 +58,7 @@ Available ruleSets:
 | [`@azure-tools/typespec-azure-core/no-rest-library-interfaces`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-rest-library-interfaces)                           | Resource interfaces from the TypeSpec.Rest.Resource library are incompatible with Azure.Core.                                                        |
 | [`@azure-tools/typespec-azure-core/no-unknown`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-unknown)                                                           | Azure services must not have properties of type `unknown`.                                                                                           |
 | [`@azure-tools/typespec-azure-core/bad-record-type`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/bad-record-type)                                                 | Identify bad record definitions.                                                                                                                     |
-| [`@azure-tools/typespec-azure-core/documentation-required`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/documentation-required)                                   | Require documentation over enums, models, and operations.                                                                                            |
+| [`@azure-tools/typespec-azure-core/documentation-required`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/documentation-required)                                   | Require meaningful documentation over enums, models, and operations.                                                                                 |
 | [`@azure-tools/typespec-azure-core/key-visibility-required`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/key-visibility-required)                                 | Key properties need to have a Lifecycle visibility setting.                                                                                          |
 | [`@azure-tools/typespec-azure-core/response-schema-problem`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/response-schema-problem)                                 | Warn about operations having multiple non-error response schemas.                                                                                    |
 | [`@azure-tools/typespec-azure-core/rpc-operation-request-body`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/rpc-operation-request-body)                           | Warning for RPC body problems.                                                                                                                       |

@@ -1,38 +1,44 @@
-Enums, models, operations, and their members/properties should have documentation. Use doc comments (`/** */`) to provide descriptions.
+Enums, models, operations, and their members/properties should have meaningful documentation. Use doc comments (`/** */`) or `@doc` to provide descriptions.
 
-## Impact
+Explicit descriptions must not be empty, whitespace-only, the placeholder `description`, or a repetition of the name they describe. Name comparisons ignore surrounding whitespace, periods, and case.
 
-- **Area:** API, SDK
+- Ordinary properties use their authored names, regardless of serialization names.
+- Operations are compared with their authored names and effective HTTP verbs. HTTP parameters and multipart parts use their HTTP names, falling back to the property name for unnamed parts.
+- Enum members and named union variants use their names; unnamed string variants use their values. HTTP status-code properties are exempt from name comparisons.
+
+Namespaces, interfaces, and scalars do not require documentation, but explicitly supplied blank descriptions are checked. Explicit documentation on inline properties and declarations exempt from missing-documentation requirements is also checked. Uninstantiated template documentation unavailable from the compiler is not checked.
 
-Missing documentation produces poor SDK reference docs and API documentation.
+## Impact
 
-## LintDiff Equivalent
+- **Area:** API, SDK
 
-This rule corresponds to the LintDiff rule [SummaryOrDescription](https://github.com/Azure/azure-openapi-validator/blob/main/docs/operation-summary-or-description.md).
+Missing or uninformative documentation produces poor SDK reference docs and API documentation.
 
 #### ❌ Incorrect
 
-Model without documentation:
+Missing documentation:
 
 ```tsp
 model Pet {
   name: string;
 }
 ```
 
-Operation without documentation:
+Descriptions that only repeat the authored names:
 
 ```tsp
-op read(): void;
+/** Widget */
+model Widget {
+  /** Name */
+  name: string;
+}
 ```
 
-Enum without documentation:
+An explicitly blank description:
 
 ```tsp
-enum PetKind {
-  Cat,
-  Dog,
-}
+@doc(" \t")
+scalar Label extends string;
 ```
 
 #### ✅ Correct
@@ -55,12 +61,15 @@ enum PetKind {
   /** A dog. */
   Dog,
 }
+
+/** A display label shown to users. */
+scalar Label extends string;
 ```
 
 :::note
-Version enums and discriminator enums/unions are exempt from this rule as they are considered self-documenting.
+Version enums and discriminator enums/unions are exempt from missing-documentation requirements as they are considered self-documenting. Explicit descriptions on these declarations are still checked for blank or uninformative content.
 :::
 
 ## Suppression
 
-Do not suppress. Add a `/** */` doc comment or an `@doc` decorator.
+Do not suppress. Add a meaningful `/** */` doc comment or an `@doc` decorator.