Skip to content

Commit 8a754f2

Browse files
authored
author-api-docs enums validation to avoid duplication (#28567)
1 parent ec53933 commit 8a754f2

1 file changed

Lines changed: 6 additions & 4 deletions

File tree

.github/prompts/author-api-docs/enumerations.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ Document within the **Properties** section of the resource that uses the enum. T
8989
```
9090

9191
2. **Create table:**
92-
- Columns: **Member** and **Description**
92+
- Columns: **Member** (required) and **Description** (optional)
9393
- List members in ascending order by numeric value (without exposing numeric values)
9494
- **For evolvable enums:**
9595
- Include `unknownFutureValue` member
@@ -133,7 +133,7 @@ Create a dedicated topic for the enumeration. This option is rarely applicable.
133133
2. **Add Members H2 section:**
134134
- **For evolvable enums (if members follow unknownFutureValue):**
135135
- Add introductory text before the table (same as Option 2)
136-
- Table with columns: **Member** and **Description**
136+
- Table with columns: **Member** (required) and **Description** (optional)
137137
- List members in ascending order by numeric value (without exposing values)
138138
- **For evolvable enums:**
139139
- Include `unknownFutureValue` member
@@ -257,21 +257,23 @@ Create a dedicated topic for the enumeration. This option is rarely applicable.
257257
- [ ] For evolvable enums with members after unknownFutureValue: Prefer header note included in property description
258258
- [ ] **Option 2 (Parent resource):**
259259
- [ ] H3 section "{enum-type} values" added after Properties table
260-
- [ ] Table has Member and Description columns
260+
- [ ] Table has Member column (required) and Description column (optional)
261261
- [ ] Members listed in ascending order by numeric value (values not exposed)
262262
- [ ] For evolvable enums: unknownFutureValue description is "Evolvable enumeration sentinel value. Do not use."
263263
- [ ] For evolvable enums with members after unknownFutureValue: Introductory text about Prefer header included
264264
- [ ] Properties table links to H3 section
265+
- [ ] Parent resource property description excludes inline value listing (values are accessible via linked H3 section)
265266
- [ ] For subnamespaces: Fully qualified enum name used
266267
- [ ] **Option 3 (Separate topic):**
267268
- [ ] File created with correct naming convention
268269
- [ ] Title is "{enum-type} enum type"
269270
- [ ] Description mentions evolvable enumeration if applicable
270-
- [ ] Members H2 section with Member and Description columns
271+
- [ ] Members H2 section with Member column (required) and Description column (optional)
271272
- [ ] For evolvable enums: unknownFutureValue description is "Evolvable enumeration sentinel value. Don't use."
272273
- [ ] For evolvable enums with members after unknownFutureValue: Introductory text about Prefer header included
273274
- [ ] For subnamespaces: Namespace attribute added in page annotation
274275
- [ ] Parent resource Properties table links to enum topic
276+
- [ ] Parent resource property description excludes inline value listing (values are accessible via linked enum topic)
275277

276278
### For updating existing enumerations
277279

0 commit comments

Comments
 (0)