Enforce fixes for missing docs

.vscode/launch.json

@@ -145,6 +145,15 @@
       "sourceMaps": true,
       "skipFiles": ["<node_internals>/**/*.js"],
       "cwd": "C:/Github/Sandbox/playground/cadl/migrate/0.37"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug Docs Generation",
+      "program": "${workspaceFolder}/packages/website/.scripts/regen-ref-docs.mjs",
+      "smartStep": true,
+      "sourceMaps": true,
+      "skipFiles": ["<node_internals>/**/*.js"]
     }
   ],
   "compounds": [

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

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/compiler"
+}

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

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/http",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/http"
+}

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

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/rest",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/rest"
+}

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

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/versioning",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/versioning"
+}

cspell.yaml

@@ -52,6 +52,7 @@ words:
   - safeint
   - segmentof
   - sfixed
+  - sint
   - strs
   - TRYIT
   - TSES

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

@@ -39,25 +39,7 @@ dec discriminator(target: Model | Union, propertyName: string)
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| propertyName | `scalar string` |  |
-
-#### Examples
-
-```typespec
-@discriminator("kind")
-union Pet{ cat: Cat, dog: Dog }
-
-model Cat {kind: "cat", meow: boolean}
-model Dog {kind: "dog", bark: boolean}
-```
-
-```typespec
-@discriminator("kind")
-model Pet{ kind: string }
-
-model Cat extends Pet {kind: "cat", meow: boolean}
-model Dog extends Pet  {kind: "dog", bark: boolean}
-```
+| propertyName | `scalar string` | The property name to use for discrimination |
 
 
 ### `@doc` {#@doc}
@@ -141,11 +123,12 @@ dec friendlyName(target: unknown, name: string, formatArgs?: unknown)
 | Name | Type | Description |
 |------|------|-------------|
 | name | `scalar string` | name the template instance should take |
-| formatArgs | `(intrinsic) unknown` |  |
+| formatArgs | `(intrinsic) unknown` | Model with key value used to interpolate the name |
 
 
 ### `@inspectType` {#@inspectType}
 
+A debugging decorator used to inspect a type.
 
 ```typespec
 dec inspectType(target: unknown, text: string)
@@ -158,11 +141,12 @@ dec inspectType(target: unknown, text: string)
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| text | `scalar string` |  |
+| text | `scalar string` | Custom text to log |
 
 
 ### `@inspectTypeName` {#@inspectTypeName}
 
+A debugging decorator used to inspect a type name.
 
 ```typespec
 dec inspectTypeName(target: unknown, text: string)
@@ -175,7 +159,7 @@ dec inspectTypeName(target: unknown, text: string)
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| text | `scalar string` |  |
+| text | `scalar string` | Custom text to log |
 
 
 ### `@key` {#@key}
@@ -193,15 +177,7 @@ dec key(target: ModelProperty, altName?: string)
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| altName | `scalar string` |  |
-
-#### Examples
-
-```typespec
-model Pet {
-@key id: string;
-}
-```
+| altName | `scalar string` | Name of the property. If not specified, the decorated property name is used. |
 
 
 ### `@knownValues` {#@knownValues}
@@ -531,24 +507,12 @@ dec visibility(target: ModelProperty, ...visibilities: string[])
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| visibilities | `model string[]` |  |
-
-#### Examples
-
-```typespec
-model Dog {
-// the service will generate an ID, so you don't need to send it.
-@visibility("read") id: int32;
-// the service will store this secret name, but won't ever return it
-@visibility("create", "update") secretName: string;
-// the regular name is always present
-name: string;
-}
-```
+| visibilities | `model string[]` | List of visibilities which apply to this property. |
 
 
 ### `@withDefaultKeyVisibility` {#@withDefaultKeyVisibility}
 
+Set the visibility of key properties in a model if not already set.
 
 ```typespec
 dec withDefaultKeyVisibility(target: Model, visibility: unknown)
@@ -561,11 +525,12 @@ dec withDefaultKeyVisibility(target: Model, visibility: unknown)
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| visibility | `(intrinsic) unknown` |  |
+| visibility | `(intrinsic) unknown` | The desired default visibility value. If a key property already has a `visibility` decorator then the default visibility is not applied. |
 
 
 ### `@withoutDefaultValues` {#@withoutDefaultValues}
 
+Returns the model with any default values removed.
 
 ```typespec
 dec withoutDefaultValues(target: Model)
@@ -581,6 +546,7 @@ None
 
 ### `@withoutOmittedProperties` {#@withoutOmittedProperties}
 
+Returns the model with the given properties omitted.
 
 ```typespec
 dec withoutOmittedProperties(target: Model, omit: string | Union)
@@ -593,11 +559,12 @@ dec withoutOmittedProperties(target: Model, omit: string | Union)
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| omit | `union string \| Union` |  |
+| omit | `union string \| Union` | List of properties to omit |
 
 
 ### `@withUpdateableProperties` {#@withUpdateableProperties}
 
+Returns the model with non-updateable properties removed.
 
 ```typespec
 dec withUpdateableProperties(target: Model)
@@ -634,34 +601,6 @@ dec withVisibility(target: Model, ...visibilities: string[])
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| visibilities | `model string[]` |  |
-
-#### Examples
-
-```typespec
-model Dog {
-@visibility("read") id: int32;
-@visibility("create", "update") secretName: string;
-name: string;
-}
-
-// The spread operator will copy all the properties of Dog into DogRead,
-// and @withVisibility will then remove those that are not visible with
-// create or update visibility.
-//
-// In this case, the id property is removed, and the name and secretName
-// properties are kept.
-@withVisibility("create", "update")
-model DogCreateOrUpdate {
-...Dog;
-}
-
-// In this case the id and name properties are kept and the secretName property
-// is removed.
-@withVisibility("read")
-model DogRead {
-...Dog;
-}
-```
+| visibilities | `model string[]` | List of visibilities which apply to this property. |
 
 

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

@@ -10,6 +10,8 @@ toc_max_heading_level: 3
 
 ### `AcceptedResponse` {#TypeSpec.Http.AcceptedResponse}
 
+The request has been accepted for processing, but processing has not yet completed.
+
 ```typespec
 model TypeSpec.Http.AcceptedResponse
 ```
@@ -42,10 +44,10 @@ model ApiKeyAuth<TLocation, TName>
 
 #### Template Parameters
 
-| Name      | Description |
-| --------- | ----------- |
-| TLocation |             |
-| TName     |             |
+| Name      | Description                 |
+| --------- | --------------------------- |
+| TLocation | The location of the API key |
+| TName     | The name of the API key     |
 
 ### `AuthorizationCodeFlow` {#TypeSpec.Http.AuthorizationCodeFlow}
 
@@ -57,6 +59,8 @@ model TypeSpec.Http.AuthorizationCodeFlow
 
 ### `BadRequestResponse` {#TypeSpec.Http.BadRequestResponse}
 
+The server could not understand the request due to invalid syntax.
+
 ```typespec
 model TypeSpec.Http.BadRequestResponse
 ```
@@ -116,18 +120,24 @@ model TypeSpec.Http.ClientCredentialsFlow
 
 ### `ConflictResponse` {#TypeSpec.Http.ConflictResponse}
 
+The request conflicts with the current state of the server.
+
 ```typespec
 model TypeSpec.Http.ConflictResponse
 ```
 
 ### `CreatedResponse` {#TypeSpec.Http.CreatedResponse}
 
+The request has succeeded and a new resource has been created as a result.
+
 ```typespec
 model TypeSpec.Http.CreatedResponse
 ```
 
 ### `ForbiddenResponse` {#TypeSpec.Http.ForbiddenResponse}
 
+Access is forbidden.
+
 ```typespec
 model TypeSpec.Http.ForbiddenResponse
 ```
@@ -150,30 +160,40 @@ model TypeSpec.Http.ImplicitFlow
 
 ### `LocationHeader` {#TypeSpec.Http.LocationHeader}
 
+The Location header contains the URL where the status of the long running operation can be checked.
+
 ```typespec
 model TypeSpec.Http.LocationHeader
 ```
 
 ### `MovedResponse` {#TypeSpec.Http.MovedResponse}
 
+The URL of the requested resource has been changed permanently. The new URL is given in the response.
+
 ```typespec
 model TypeSpec.Http.MovedResponse
 ```
 
 ### `NoContentResponse` {#TypeSpec.Http.NoContentResponse}
 
+There is no content to send for this request, but the headers may be useful.
+
 ```typespec
 model TypeSpec.Http.NoContentResponse
 ```
 
 ### `NotFoundResponse` {#TypeSpec.Http.NotFoundResponse}
 
+The server cannot find the requested resource.
+
 ```typespec
 model TypeSpec.Http.NotFoundResponse
 ```
 
 ### `NotModifiedResponse` {#TypeSpec.Http.NotModifiedResponse}
 
+The client has made a conditional request and the resource has not been modified.
+
 ```typespec
 model TypeSpec.Http.NotModifiedResponse
 ```
@@ -191,12 +211,14 @@ model OAuth2Auth<TFlows>
 
 #### Template Parameters
 
-| Name   | Description |
-| ------ | ----------- |
-| TFlows |             |
+| Name   | Description                        |
+| ------ | ---------------------------------- |
+| TFlows | The list of supported OAuth2 flows |
 
 ### `OkResponse` {#TypeSpec.Http.OkResponse}
 
+The request has succeeded.
+
 ```typespec
 model TypeSpec.Http.OkResponse
 ```
@@ -248,6 +270,8 @@ model Response<Status>
 
 ### `UnauthorizedResponse` {#TypeSpec.Http.UnauthorizedResponse}
 
+Access is unauthorized.
+
 ```typespec
 model TypeSpec.Http.UnauthorizedResponse
 ```