Skip to content

Commit 48a1492

Browse files
tjprescotttjprescott
authored
Enforce fixes for missing docs (microsoft#1860)
* Add doc errors for decorators and decorator parameters. * Add decorator documentation rules. * Code review feedback. * Update logic. * Compiler docs fixes. * Doc updates. * Fix protobuf issues. * Code review feedback. * Test that build fails... * Add support for scalars. * I hate EVERYTHING about you, cSpell.... * Code review feedback.
1 parent bba114b commit 48a1492

34 files changed

+1087
-409
lines changed

‎.vscode/launch.json

+9
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,15 @@
145145
"sourceMaps": true,
146146
"skipFiles": ["<node_internals>/**/*.js"],
147147
"cwd": "C:/Github/Sandbox/playground/cadl/migrate/0.37"
148+
},
149+
{
150+
"type": "node",
151+
"request": "launch",
152+
"name": "Debug Docs Generation",
153+
"program": "${workspaceFolder}/packages/website/.scripts/regen-ref-docs.mjs",
154+
"smartStep": true,
155+
"sourceMaps": true,
156+
"skipFiles": ["<node_internals>/**/*.js"]
148157
}
149158
],
150159
"compounds": [

‎common/changes/@typespec/compiler/docs-FixMissingDocs_2023-04-26-23-23.json

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@typespec/compiler",
5+
"comment": "",
6+
"type": "none"
7+
}
8+
],
9+
"packageName": "@typespec/compiler"
10+
}

‎common/changes/@typespec/http/docs-FixMissingDocs_2023-04-26-23-23.json

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@typespec/http",
5+
"comment": "",
6+
"type": "none"
7+
}
8+
],
9+
"packageName": "@typespec/http"
10+
}

‎common/changes/@typespec/rest/docs-FixMissingDocs_2023-04-26-23-23.json

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@typespec/rest",
5+
"comment": "",
6+
"type": "none"
7+
}
8+
],
9+
"packageName": "@typespec/rest"
10+
}

‎common/changes/@typespec/versioning/docs-FixMissingDocs_2023-04-26-23-23.json

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@typespec/versioning",
5+
"comment": "",
6+
"type": "none"
7+
}
8+
],
9+
"packageName": "@typespec/versioning"
10+
}

‎cspell.yaml

+1
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ words:
5252
- safeint
5353
- segmentof
5454
- sfixed
55+
- sint
5556
- strs
5657
- TRYIT
5758
- TSES

‎docs/standard-library/built-in-decorators.md

+15-76
Original file line numberDiff line numberDiff line change
@@ -39,25 +39,7 @@ dec discriminator(target: Model | Union, propertyName: string)
3939
#### Parameters
4040
| Name | Type | Description |
4141
|------|------|-------------|
42-
| propertyName | `scalar string` | |
43-
44-
#### Examples
45-
46-
```typespec
47-
@discriminator("kind")
48-
union Pet{ cat: Cat, dog: Dog }
49-
50-
model Cat {kind: "cat", meow: boolean}
51-
model Dog {kind: "dog", bark: boolean}
52-
```
53-
54-
```typespec
55-
@discriminator("kind")
56-
model Pet{ kind: string }
57-
58-
model Cat extends Pet {kind: "cat", meow: boolean}
59-
model Dog extends Pet {kind: "dog", bark: boolean}
60-
```
42+
| propertyName | `scalar string` | The property name to use for discrimination |
6143

6244

6345
### `@doc` {#@doc}
@@ -141,11 +123,12 @@ dec friendlyName(target: unknown, name: string, formatArgs?: unknown)
141123
| Name | Type | Description |
142124
|------|------|-------------|
143125
| name | `scalar string` | name the template instance should take |
144-
| formatArgs | `(intrinsic) unknown` | |
126+
| formatArgs | `(intrinsic) unknown` | Model with key value used to interpolate the name |
145127

146128

147129
### `@inspectType` {#@inspectType}
148130

131+
A debugging decorator used to inspect a type.
149132

150133
```typespec
151134
dec inspectType(target: unknown, text: string)
@@ -158,11 +141,12 @@ dec inspectType(target: unknown, text: string)
158141
#### Parameters
159142
| Name | Type | Description |
160143
|------|------|-------------|
161-
| text | `scalar string` | |
144+
| text | `scalar string` | Custom text to log |
162145

163146

164147
### `@inspectTypeName` {#@inspectTypeName}
165148

149+
A debugging decorator used to inspect a type name.
166150

167151
```typespec
168152
dec inspectTypeName(target: unknown, text: string)
@@ -175,7 +159,7 @@ dec inspectTypeName(target: unknown, text: string)
175159
#### Parameters
176160
| Name | Type | Description |
177161
|------|------|-------------|
178-
| text | `scalar string` | |
162+
| text | `scalar string` | Custom text to log |
179163

180164

181165
### `@key` {#@key}
@@ -193,15 +177,7 @@ dec key(target: ModelProperty, altName?: string)
193177
#### Parameters
194178
| Name | Type | Description |
195179
|------|------|-------------|
196-
| altName | `scalar string` | |
197-
198-
#### Examples
199-
200-
```typespec
201-
model Pet {
202-
@key id: string;
203-
}
204-
```
180+
| altName | `scalar string` | Name of the property. If not specified, the decorated property name is used. |
205181

206182

207183
### `@knownValues` {#@knownValues}
@@ -531,24 +507,12 @@ dec visibility(target: ModelProperty, ...visibilities: string[])
531507
#### Parameters
532508
| Name | Type | Description |
533509
|------|------|-------------|
534-
| visibilities | `model string[]` | |
535-
536-
#### Examples
537-
538-
```typespec
539-
model Dog {
540-
// the service will generate an ID, so you don't need to send it.
541-
@visibility("read") id: int32;
542-
// the service will store this secret name, but won't ever return it
543-
@visibility("create", "update") secretName: string;
544-
// the regular name is always present
545-
name: string;
546-
}
547-
```
510+
| visibilities | `model string[]` | List of visibilities which apply to this property. |
548511

549512

550513
### `@withDefaultKeyVisibility` {#@withDefaultKeyVisibility}
551514

515+
Set the visibility of key properties in a model if not already set.
552516

553517
```typespec
554518
dec withDefaultKeyVisibility(target: Model, visibility: unknown)
@@ -561,11 +525,12 @@ dec withDefaultKeyVisibility(target: Model, visibility: unknown)
561525
#### Parameters
562526
| Name | Type | Description |
563527
|------|------|-------------|
564-
| visibility | `(intrinsic) unknown` | |
528+
| visibility | `(intrinsic) unknown` | The desired default visibility value. If a key property already has a `visibility` decorator then the default visibility is not applied. |
565529

566530

567531
### `@withoutDefaultValues` {#@withoutDefaultValues}
568532

533+
Returns the model with any default values removed.
569534

570535
```typespec
571536
dec withoutDefaultValues(target: Model)
@@ -581,6 +546,7 @@ None
581546

582547
### `@withoutOmittedProperties` {#@withoutOmittedProperties}
583548

549+
Returns the model with the given properties omitted.
584550

585551
```typespec
586552
dec withoutOmittedProperties(target: Model, omit: string | Union)
@@ -593,11 +559,12 @@ dec withoutOmittedProperties(target: Model, omit: string | Union)
593559
#### Parameters
594560
| Name | Type | Description |
595561
|------|------|-------------|
596-
| omit | `union string \| Union` | |
562+
| omit | `union string \| Union` | List of properties to omit |
597563

598564

599565
### `@withUpdateableProperties` {#@withUpdateableProperties}
600566

567+
Returns the model with non-updateable properties removed.
601568

602569
```typespec
603570
dec withUpdateableProperties(target: Model)
@@ -634,34 +601,6 @@ dec withVisibility(target: Model, ...visibilities: string[])
634601
#### Parameters
635602
| Name | Type | Description |
636603
|------|------|-------------|
637-
| visibilities | `model string[]` | |
638-
639-
#### Examples
640-
641-
```typespec
642-
model Dog {
643-
@visibility("read") id: int32;
644-
@visibility("create", "update") secretName: string;
645-
name: string;
646-
}
647-
648-
// The spread operator will copy all the properties of Dog into DogRead,
649-
// and @withVisibility will then remove those that are not visible with
650-
// create or update visibility.
651-
//
652-
// In this case, the id property is removed, and the name and secretName
653-
// properties are kept.
654-
@withVisibility("create", "update")
655-
model DogCreateOrUpdate {
656-
...Dog;
657-
}
658-
659-
// In this case the id and name properties are kept and the secretName property
660-
// is removed.
661-
@withVisibility("read")
662-
model DogRead {
663-
...Dog;
664-
}
665-
```
604+
| visibilities | `model string[]` | List of visibilities which apply to this property. |
666605

667606

‎docs/standard-library/http/reference/data-types.md

+31-7
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ toc_max_heading_level: 3
1010

1111
### `AcceptedResponse` {#TypeSpec.Http.AcceptedResponse}
1212

13+
The request has been accepted for processing, but processing has not yet completed.
14+
1315
```typespec
1416
model TypeSpec.Http.AcceptedResponse
1517
```
@@ -42,10 +44,10 @@ model ApiKeyAuth<TLocation, TName>
4244

4345
#### Template Parameters
4446

45-
| Name | Description |
46-
| --------- | ----------- |
47-
| TLocation | |
48-
| TName | |
47+
| Name | Description |
48+
| --------- | --------------------------- |
49+
| TLocation | The location of the API key |
50+
| TName | The name of the API key |
4951

5052
### `AuthorizationCodeFlow` {#TypeSpec.Http.AuthorizationCodeFlow}
5153

@@ -57,6 +59,8 @@ model TypeSpec.Http.AuthorizationCodeFlow
5759

5860
### `BadRequestResponse` {#TypeSpec.Http.BadRequestResponse}
5961

62+
The server could not understand the request due to invalid syntax.
63+
6064
```typespec
6165
model TypeSpec.Http.BadRequestResponse
6266
```
@@ -116,18 +120,24 @@ model TypeSpec.Http.ClientCredentialsFlow
116120

117121
### `ConflictResponse` {#TypeSpec.Http.ConflictResponse}
118122

123+
The request conflicts with the current state of the server.
124+
119125
```typespec
120126
model TypeSpec.Http.ConflictResponse
121127
```
122128

123129
### `CreatedResponse` {#TypeSpec.Http.CreatedResponse}
124130

131+
The request has succeeded and a new resource has been created as a result.
132+
125133
```typespec
126134
model TypeSpec.Http.CreatedResponse
127135
```
128136

129137
### `ForbiddenResponse` {#TypeSpec.Http.ForbiddenResponse}
130138

139+
Access is forbidden.
140+
131141
```typespec
132142
model TypeSpec.Http.ForbiddenResponse
133143
```
@@ -150,30 +160,40 @@ model TypeSpec.Http.ImplicitFlow
150160

151161
### `LocationHeader` {#TypeSpec.Http.LocationHeader}
152162

163+
The Location header contains the URL where the status of the long running operation can be checked.
164+
153165
```typespec
154166
model TypeSpec.Http.LocationHeader
155167
```
156168

157169
### `MovedResponse` {#TypeSpec.Http.MovedResponse}
158170

171+
The URL of the requested resource has been changed permanently. The new URL is given in the response.
172+
159173
```typespec
160174
model TypeSpec.Http.MovedResponse
161175
```
162176

163177
### `NoContentResponse` {#TypeSpec.Http.NoContentResponse}
164178

179+
There is no content to send for this request, but the headers may be useful.
180+
165181
```typespec
166182
model TypeSpec.Http.NoContentResponse
167183
```
168184

169185
### `NotFoundResponse` {#TypeSpec.Http.NotFoundResponse}
170186

187+
The server cannot find the requested resource.
188+
171189
```typespec
172190
model TypeSpec.Http.NotFoundResponse
173191
```
174192

175193
### `NotModifiedResponse` {#TypeSpec.Http.NotModifiedResponse}
176194

195+
The client has made a conditional request and the resource has not been modified.
196+
177197
```typespec
178198
model TypeSpec.Http.NotModifiedResponse
179199
```
@@ -191,12 +211,14 @@ model OAuth2Auth<TFlows>
191211

192212
#### Template Parameters
193213

194-
| Name | Description |
195-
| ------ | ----------- |
196-
| TFlows | |
214+
| Name | Description |
215+
| ------ | ---------------------------------- |
216+
| TFlows | The list of supported OAuth2 flows |
197217

198218
### `OkResponse` {#TypeSpec.Http.OkResponse}
199219

220+
The request has succeeded.
221+
200222
```typespec
201223
model TypeSpec.Http.OkResponse
202224
```
@@ -248,6 +270,8 @@ model Response<Status>
248270

249271
### `UnauthorizedResponse` {#TypeSpec.Http.UnauthorizedResponse}
250272

273+
Access is unauthorized.
274+
251275
```typespec
252276
model TypeSpec.Http.UnauthorizedResponse
253277
```

0 commit comments

Comments
 (0)