diff --git a/.vscode/launch.json b/.vscode/launch.json index 33f4167f032..330667600aa 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -145,6 +145,15 @@ "sourceMaps": true, "skipFiles": ["/**/*.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": ["/**/*.js"] } ], "compounds": [ diff --git a/common/changes/@typespec/compiler/docs-FixMissingDocs_2023-04-26-23-23.json b/common/changes/@typespec/compiler/docs-FixMissingDocs_2023-04-26-23-23.json new file mode 100644 index 00000000000..5945164bd23 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/common/changes/@typespec/http/docs-FixMissingDocs_2023-04-26-23-23.json b/common/changes/@typespec/http/docs-FixMissingDocs_2023-04-26-23-23.json new file mode 100644 index 00000000000..e59b9bb12e2 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/common/changes/@typespec/rest/docs-FixMissingDocs_2023-04-26-23-23.json b/common/changes/@typespec/rest/docs-FixMissingDocs_2023-04-26-23-23.json new file mode 100644 index 00000000000..64135d54e31 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/common/changes/@typespec/versioning/docs-FixMissingDocs_2023-04-26-23-23.json b/common/changes/@typespec/versioning/docs-FixMissingDocs_2023-04-26-23-23.json new file mode 100644 index 00000000000..3c8fd8571b8 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/cspell.yaml b/cspell.yaml index 206d291b5e6..49113244276 100644 --- a/cspell.yaml +++ b/cspell.yaml @@ -52,6 +52,7 @@ words: - safeint - segmentof - sfixed + - sint - strs - TRYIT - TSES diff --git a/docs/standard-library/built-in-decorators.md b/docs/standard-library/built-in-decorators.md index 6640dcba5ce..26758262a6b 100644 --- a/docs/standard-library/built-in-decorators.md +++ b/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. | diff --git a/docs/standard-library/http/reference/data-types.md b/docs/standard-library/http/reference/data-types.md index fe0d34604f4..e62463006a2 100644 --- a/docs/standard-library/http/reference/data-types.md +++ b/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 #### 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 #### 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 ### `UnauthorizedResponse` {#TypeSpec.Http.UnauthorizedResponse} +Access is unauthorized. + ```typespec model TypeSpec.Http.UnauthorizedResponse ``` diff --git a/docs/standard-library/http/reference/decorators.md b/docs/standard-library/http/reference/decorators.md index 5076c235dcb..3b3134e8f86 100644 --- a/docs/standard-library/http/reference/decorators.md +++ b/docs/standard-library/http/reference/decorators.md @@ -129,9 +129,9 @@ dec TypeSpec.Http.includeInapplicableMetadataInPayload(target: unknown, value: b #### Parameters -| Name | Type | Description | -| ----- | ---------------- | ----------- | -| value | `scalar boolean` | | +| Name | Type | Description | +| ----- | ---------------- | --------------------------------------------------------------- | +| value | `scalar boolean` | If true, inapplicable metadata will be included in the payload. | ### `@patch` {#@TypeSpec.Http.patch} @@ -255,10 +255,10 @@ dec TypeSpec.Http.route(target: Namespace | Interface | Operation, path: string, #### Parameters -| Name | Type | Description | -| ------- | ------------------------- | ----------------------------------------------------- | -| path | `scalar string` | Relative route path. Cannot include query parameters. | -| options | `model (anonymous model)` | | +| Name | Type | Description | +| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| path | `scalar string` | Relative route path. Cannot include query parameters. | +| options | `model (anonymous model)` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | ### `@server` {#@TypeSpec.Http.server} diff --git a/docs/standard-library/protobuf/reference/data-types.md b/docs/standard-library/protobuf/reference/data-types.md index 9fbd600810c..2e12b4fb8a3 100644 --- a/docs/standard-library/protobuf/reference/data-types.md +++ b/docs/standard-library/protobuf/reference/data-types.md @@ -75,3 +75,75 @@ See the [`@stream`](./decorators# ```typespec enum TypeSpec.Protobuf.StreamMode ``` + +### `fixed32` {#TypeSpec.Protobuf.fixed32} + +An unsigned 32-bit integer that will use the `fixed32` encoding when used in a Protobuf message. + +#### Protobuf binary format + +Always four bytes. More efficient than `uint32` if values are often greater than 228. + +```typespec +scalar TypeSpec.Protobuf.fixed32 +``` + +### `fixed64` {#TypeSpec.Protobuf.fixed64} + +An unsigned 64-bit integer that will use the `fixed64` encoding when used in a Protobuf message. + +#### Protobuf binary format + +Always eight bytes. More efficient than `uint64` if values are often greater than 256. + +```typespec +scalar TypeSpec.Protobuf.fixed64 +``` + +### `sfixed32` {#TypeSpec.Protobuf.sfixed32} + +A signed 32-bit integer that will use the `sfixed32` encoding when used in a Protobuf message. + +#### Protobuf binary format + +Always four bytes. + +```typespec +scalar TypeSpec.Protobuf.sfixed32 +``` + +### `sfixed64` {#TypeSpec.Protobuf.sfixed64} + +A signed 64-bit integer that will use the `sfixed64` encoding when used in a Protobuf message. + +#### Protobuf binary format + +Always eight bytes. + +```typespec +scalar TypeSpec.Protobuf.sfixed64 +``` + +### `sint32` {#TypeSpec.Protobuf.sint32} + +A signed 32-bit integer that will use the `sint32` encoding when used in a Protobuf message. + +#### Protobuf binary format + +Uses variable-length encoding. These more efficiently encode negative numbers than regular int32s. + +```typespec +scalar TypeSpec.Protobuf.sint32 +``` + +### `sint64` {#TypeSpec.Protobuf.sint64} + +A signed 64-bit integer that will use the `sint64` encoding when used in a Protobuf message. + +#### Protobuf binary format + +Uses variable-length encoding. These more efficiently encode negative numbers than regular `int64s`. + +```typespec +scalar TypeSpec.Protobuf.sint64 +``` diff --git a/docs/standard-library/rest/reference/data-types.md b/docs/standard-library/rest/reference/data-types.md index a8f44f82fb5..415b46354f2 100644 --- a/docs/standard-library/rest/reference/data-types.md +++ b/docs/standard-library/rest/reference/data-types.md @@ -6,6 +6,16 @@ toc_max_heading_level: 3 # Data types +## TypeSpec.Rest + +### `ResourceLocation` {#TypeSpec.Rest.ResourceLocation} + +A URL that points to a resource. + +```typespec +scalar TypeSpec.Rest.ResourceLocation +``` + ## TypeSpec.Rest.Resource ### `CollectionWithNextLink` {#TypeSpec.Rest.Resource.CollectionWithNextLink} @@ -20,9 +30,9 @@ model CollectionWithNextLink #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource type of the collection. | ### `CollectionWithNextLink` {#TypeSpec.Rest.Resource.CollectionWithNextLink} @@ -36,9 +46,9 @@ model CollectionWithNextLink #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource type of the collection. | ### `CollectionWithNextLink` {#TypeSpec.Rest.Resource.CollectionWithNextLink} @@ -52,9 +62,9 @@ model CollectionWithNextLink #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource type of the collection. | ### `CollectionWithNextLink` {#TypeSpec.Rest.Resource.CollectionWithNextLink} @@ -68,9 +78,9 @@ model CollectionWithNextLink #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource type of the collection. | ### `CollectionWithNextLink` {#TypeSpec.Rest.Resource.CollectionWithNextLink} @@ -84,9 +94,9 @@ model CollectionWithNextLink #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource type of the collection. | ### `CollectionWithNextLink` {#TypeSpec.Rest.Resource.CollectionWithNextLink} @@ -100,9 +110,9 @@ model CollectionWithNextLink #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource type of the collection. | ### `CollectionWithNextLink` {#TypeSpec.Rest.Resource.CollectionWithNextLink} @@ -116,393 +126,457 @@ model CollectionWithNextLink #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource type of the collection. | ### `KeysOf` {#TypeSpec.Rest.Resource.KeysOf} +Dynamically gathers keys of the model type T. + ```typespec model KeysOf ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ----------------- | +| T | The target model. | ### `ParentKeysOf` {#TypeSpec.Rest.Resource.ParentKeysOf} +Dynamically gathers parent keys of the model type T. + ```typespec model ParentKeysOf ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ----------------- | +| T | The target model. | ### `ResourceCollectionParameters` {#TypeSpec.Rest.Resource.ResourceCollectionParameters} +Represents collection operation parameters for resource TResource. + ```typespec model ResourceCollectionParameters ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | ------------------- | +| TResource | The resource model. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} +Resource create operation completed successfully. + ```typespec model ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource model that was created. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} +Resource create operation completed successfully. + ```typespec model ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource model that was created. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} +Resource create operation completed successfully. + ```typespec model ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource model that was created. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} +Resource create operation completed successfully. + ```typespec model ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource model that was created. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} +Resource create operation completed successfully. + ```typespec model ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource model that was created. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} +Resource create operation completed successfully. + ```typespec model ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource model that was created. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} +Resource create operation completed successfully. + ```typespec model ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource model that was created. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} +Resource create operation completed successfully. + ```typespec model ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource model that was created. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} +Resource create operation completed successfully. + ```typespec model ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource model that was created. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} +Resource create operation completed successfully. + ```typespec model ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ----------- | -| T | | +| Name | Description | +| ---- | ------------------------------------ | +| T | The resource model that was created. | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} +Resource create operation model. + ```typespec model ResourceCreateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to create. | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} +Resource create operation model. + ```typespec model ResourceCreateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to create. | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} +Resource create operation model. + ```typespec model ResourceCreateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to create. | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} +Resource create operation model. + ```typespec model ResourceCreateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to create. | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} +Resource create operation model. + ```typespec model ResourceCreateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to create. | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} +Resource create operation model. + ```typespec model ResourceCreateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to create. | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} +Resource create operation model. + ```typespec model ResourceCreateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to create. | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} +Resource create operation model. + ```typespec model ResourceCreateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to create. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} +Resource create or update operation model. + ```typespec model ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | ### `ResourceDeletedResponse` {#TypeSpec.Rest.Resource.ResourceDeletedResponse} @@ -522,12 +596,14 @@ model TypeSpec.Rest.Resource.ResourceError ### `ResourceParameters` {#TypeSpec.Rest.Resource.ResourceParameters} +Represents operation parameters for resource TResource. + ```typespec model ResourceParameters ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | +| Name | Description | +| --------- | ------------------- | +| TResource | The resource model. | diff --git a/docs/standard-library/rest/reference/decorators.md b/docs/standard-library/rest/reference/decorators.md index 4028cfae4d2..f90fa85e02e 100644 --- a/docs/standard-library/rest/reference/decorators.md +++ b/docs/standard-library/rest/reference/decorators.md @@ -10,7 +10,7 @@ toc_max_heading_level: 3 ### `@action` {#@TypeSpec.Rest.action} -Specify this operation is an action. (Scopped to a resource item /pets/{petId}/my-action) +Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my-action) ```typespec dec TypeSpec.Rest.action(target: Operation, name?: string) @@ -22,9 +22,9 @@ dec TypeSpec.Rest.action(target: Operation, name?: string) #### Parameters -| Name | Type | Description | -| ---- | --------------- | ----------- | -| name | `scalar string` | | +| Name | Type | Description | +| ---- | --------------- | ----------------------------------------------------------------------------- | +| name | `scalar string` | Name of the action. If not specified, the name of the operation will be used. | ### `@actionSeparator` {#@TypeSpec.Rest.actionSeparator} @@ -83,10 +83,10 @@ dec TypeSpec.Rest.collectionAction(target: Operation, resourceType: Model, name? #### Parameters -| Name | Type | Description | -| ------------ | --------------- | ----------- | -| resourceType | `Model` | | -| name | `scalar string` | | +| Name | Type | Description | +| ------------ | --------------- | ----------------------------------------------------------------------------- | +| resourceType | `Model` | Resource marked with | +| name | `scalar string` | Name of the action. If not specified, the name of the operation will be used. | ### `@createsOrReplacesResource` {#@TypeSpec.Rest.createsOrReplacesResource} @@ -102,9 +102,9 @@ dec TypeSpec.Rest.createsOrReplacesResource(target: Operation, resourceType: Mod #### Parameters -| Name | Type | Description | -| ------------ | ------- | ----------- | -| resourceType | `Model` | | +| Name | Type | Description | +| ------------ | ------- | -------------------- | +| resourceType | `Model` | Resource marked with | ### `@createsOrUpdatesResource` {#@TypeSpec.Rest.createsOrUpdatesResource} @@ -120,9 +120,9 @@ dec TypeSpec.Rest.createsOrUpdatesResource(target: Operation, resourceType: Mode #### Parameters -| Name | Type | Description | -| ------------ | ------- | ----------- | -| resourceType | `Model` | | +| Name | Type | Description | +| ------------ | ------- | -------------------- | +| resourceType | `Model` | Resource marked with | ### `@createsResource` {#@TypeSpec.Rest.createsResource} @@ -138,9 +138,9 @@ dec TypeSpec.Rest.createsResource(target: Operation, resourceType: Model) #### Parameters -| Name | Type | Description | -| ------------ | ------- | ----------- | -| resourceType | `Model` | | +| Name | Type | Description | +| ------------ | ------- | -------------------- | +| resourceType | `Model` | Resource marked with | ### `@deletesResource` {#@TypeSpec.Rest.deletesResource} @@ -156,9 +156,9 @@ dec TypeSpec.Rest.deletesResource(target: Operation, resourceType: Model) #### Parameters -| Name | Type | Description | -| ------------ | ------- | ----------- | -| resourceType | `Model` | | +| Name | Type | Description | +| ------------ | ------- | -------------------- | +| resourceType | `Model` | Resource marked with | ### `@listsResource` {#@TypeSpec.Rest.listsResource} @@ -174,9 +174,9 @@ dec TypeSpec.Rest.listsResource(target: Operation, resourceType: Model) #### Parameters -| Name | Type | Description | -| ------------ | ------- | ----------- | -| resourceType | `Model` | | +| Name | Type | Description | +| ------------ | ------- | -------------------- | +| resourceType | `Model` | Resource marked with | ### `@readsResource` {#@TypeSpec.Rest.readsResource} @@ -192,9 +192,9 @@ dec TypeSpec.Rest.readsResource(target: Operation, resourceType: Model) #### Parameters -| Name | Type | Description | -| ------------ | ------- | ----------- | -| resourceType | `Model` | | +| Name | Type | Description | +| ------------ | ------- | -------------------- | +| resourceType | `Model` | Resource marked with | ### `@resource` {#@TypeSpec.Rest.resource} @@ -246,9 +246,9 @@ dec TypeSpec.Rest.segmentOf(target: Operation, type: Model) #### Parameters -| Name | Type | Description | -| ---- | ------- | ----------- | -| type | `Model` | | +| Name | Type | Description | +| ---- | ------- | ------------ | +| type | `Model` | Target model | ### `@updatesResource` {#@TypeSpec.Rest.updatesResource} @@ -264,6 +264,6 @@ dec TypeSpec.Rest.updatesResource(target: Operation, resourceType: Model) #### Parameters -| Name | Type | Description | -| ------------ | ------- | ----------- | -| resourceType | `Model` | | +| Name | Type | Description | +| ------------ | ------- | -------------------- | +| resourceType | `Model` | Resource marked with | diff --git a/docs/standard-library/rest/reference/interfaces.md b/docs/standard-library/rest/reference/interfaces.md index 7d7b57c5e49..dc22285f1b3 100644 --- a/docs/standard-library/rest/reference/interfaces.md +++ b/docs/standard-library/rest/reference/interfaces.md @@ -10,233 +10,267 @@ toc_max_heading_level: 3 ### `ExtensionResourceCollectionOperations` {#TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations} +Extension resource operation templates for extension resource collections. + ```typespec interface TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TExtension | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TExtension | The extension resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `ExtensionResourceCreate` {#TypeSpec.Rest.Resource.ExtensionResourceCreate} +Extension resource create operation template. + ```typespec interface TypeSpec.Rest.Resource.ExtensionResourceCreate ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TExtension | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TExtension | The extension resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `ExtensionResourceCreateOrUpdate` {#TypeSpec.Rest.Resource.ExtensionResourceCreateOrUpdate} +Extension resource create or update operation template. + ```typespec interface TypeSpec.Rest.Resource.ExtensionResourceCreateOrUpdate ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TExtension | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TExtension | The extension resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `ExtensionResourceDelete` {#TypeSpec.Rest.Resource.ExtensionResourceDelete} +Extension resource delete operation template. + ```typespec interface TypeSpec.Rest.Resource.ExtensionResourceDelete ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TExtension | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TExtension | The extension resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `ExtensionResourceInstanceOperations` {#TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations} +Extension resource operation templates for extension resource instances. + ```typespec interface TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TExtension | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TExtension | The extension resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `ExtensionResourceList` {#TypeSpec.Rest.Resource.ExtensionResourceList} +Extension resource list operation template. + ```typespec interface TypeSpec.Rest.Resource.ExtensionResourceList ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TExtension | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TExtension | The extension resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `ExtensionResourceOperations` {#TypeSpec.Rest.Resource.ExtensionResourceOperations} +Extension resource operation templates for extension resource instances and collections. + ```typespec interface TypeSpec.Rest.Resource.ExtensionResourceOperations ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TExtension | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TExtension | The extension resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `ExtensionResourceRead` {#TypeSpec.Rest.Resource.ExtensionResourceRead} +Extension resource read operation template. + ```typespec interface TypeSpec.Rest.Resource.ExtensionResourceRead ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TExtension | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TExtension | The extension resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `ExtensionResourceUpdate` {#TypeSpec.Rest.Resource.ExtensionResourceUpdate} +Extension resource update operation template. + ```typespec interface TypeSpec.Rest.Resource.ExtensionResourceUpdate ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TExtension | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TExtension | The extension resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `ResourceCollectionOperations` {#TypeSpec.Rest.Resource.ResourceCollectionOperations} +Resource operation templates for resource collections. + ```typespec interface TypeSpec.Rest.Resource.ResourceCollectionOperations ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | -| TError | | +| Name | Description | +| --------- | ------------------- | +| TResource | The resource model. | +| TError | The error response. | ### `ResourceCreate` {#TypeSpec.Rest.Resource.ResourceCreate} +Resource create operation template. + ```typespec interface TypeSpec.Rest.Resource.ResourceCreate ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | -| TError | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to create. | +| TError | The error response. | ### `ResourceCreateOrReplace` {#TypeSpec.Rest.Resource.ResourceCreateOrReplace} +Resource create or replace operation template. + ```typespec interface TypeSpec.Rest.Resource.ResourceCreateOrReplace ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | -| TError | | +| Name | Description | +| --------- | ---------------------------------------- | +| TResource | The resource model to create or replace. | +| TError | The error response. | ### `ResourceCreateOrUpdate` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdate} +Resource create or update operation template. + ```typespec interface TypeSpec.Rest.Resource.ResourceCreateOrUpdate ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | -| TError | | +| Name | Description | +| --------- | --------------------------------------- | +| TResource | The resource model to create or update. | +| TError | The error response. | ### `ResourceDelete` {#TypeSpec.Rest.Resource.ResourceDelete} +Resource delete operation template. + ```typespec interface TypeSpec.Rest.Resource.ResourceDelete ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | -| TError | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to delete. | +| TError | The error response. | ### `ResourceInstanceOperations` {#TypeSpec.Rest.Resource.ResourceInstanceOperations} +Resource operation templates for resource instances. + ```typespec interface TypeSpec.Rest.Resource.ResourceInstanceOperations ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | -| TError | | +| Name | Description | +| --------- | ------------------- | +| TResource | The resource model. | +| TError | The error response. | ### `ResourceList` {#TypeSpec.Rest.Resource.ResourceList} +Resource list operation template. + ```typespec interface TypeSpec.Rest.Resource.ResourceList ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | -| TError | | +| Name | Description | +| --------- | --------------------------- | +| TResource | The resource model to list. | +| TError | The error response. | ### `ResourceOperations` {#TypeSpec.Rest.Resource.ResourceOperations} +Resource operation templates for resources. + ```typespec interface TypeSpec.Rest.Resource.ResourceOperations ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | -| TError | | +| Name | Description | +| --------- | ------------------- | +| TResource | The resource model. | +| TError | The error response. | ### `ResourceRead` {#TypeSpec.Rest.Resource.ResourceRead} @@ -255,55 +289,63 @@ interface TypeSpec.Rest.Resource.ResourceRead ### `ResourceUpdate` {#TypeSpec.Rest.Resource.ResourceUpdate} +Resource update operation template. + ```typespec interface TypeSpec.Rest.Resource.ResourceUpdate ``` #### Template Parameters -| Name | Description | -| --------- | ----------- | -| TResource | | -| TError | | +| Name | Description | +| --------- | ----------------------------- | +| TResource | The resource model to update. | +| TError | The error response. | ### `SingletonResourceOperations` {#TypeSpec.Rest.Resource.SingletonResourceOperations} +Singleton resource operation templates for singleton resource instances. + ```typespec interface TypeSpec.Rest.Resource.SingletonResourceOperations ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TSingleton | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TSingleton | The singleton resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `SingletonResourceRead` {#TypeSpec.Rest.Resource.SingletonResourceRead} +Singleton resource read operation template. + ```typespec interface TypeSpec.Rest.Resource.SingletonResourceRead ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TSingleton | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TSingleton | The singleton resource model. | +| TResource | The resource model. | +| TError | The error response. | ### `SingletonResourceUpdate` {#TypeSpec.Rest.Resource.SingletonResourceUpdate} +Singleton resource update operation template. + ```typespec interface TypeSpec.Rest.Resource.SingletonResourceUpdate ``` #### Template Parameters -| Name | Description | -| ---------- | ----------- | -| TSingleton | | -| TResource | | -| TError | | +| Name | Description | +| ---------- | ----------------------------- | +| TSingleton | The singleton resource model. | +| TResource | The resource model. | +| TError | The error response. | diff --git a/docs/standard-library/versioning/reference/decorators.md b/docs/standard-library/versioning/reference/decorators.md index f21cdef20aa..5ae204491e8 100644 --- a/docs/standard-library/versioning/reference/decorators.md +++ b/docs/standard-library/versioning/reference/decorators.md @@ -22,9 +22,9 @@ dec TypeSpec.Versioning.added(target: unknown, version: EnumMember) #### Parameters -| Name | Type | Description | -| ------- | ------------ | ----------- | -| version | `EnumMember` | | +| Name | Type | Description | +| ------- | ------------ | ----------------------------------------- | +| version | `EnumMember` | The version that the target was added in. | ### `@madeOptional` {#@TypeSpec.Versioning.madeOptional} @@ -40,9 +40,9 @@ dec TypeSpec.Versioning.madeOptional(target: unknown, version: EnumMember) #### Parameters -| Name | Type | Description | -| ------- | ------------ | ----------- | -| version | `EnumMember` | | +| Name | Type | Description | +| ------- | ------------ | ------------------------------------------------- | +| version | `EnumMember` | The version that the target was made optional in. | ### `@removed` {#@TypeSpec.Versioning.removed} @@ -58,9 +58,9 @@ dec TypeSpec.Versioning.removed(target: unknown, version: EnumMember) #### Parameters -| Name | Type | Description | -| ------- | ------------ | ----------- | -| version | `EnumMember` | | +| Name | Type | Description | +| ------- | ------------ | ------------------------------------------- | +| version | `EnumMember` | The version that the target was removed in. | ### `@renamedFrom` {#@TypeSpec.Versioning.renamedFrom} @@ -76,10 +76,10 @@ dec TypeSpec.Versioning.renamedFrom(target: unknown, version: EnumMember, oldNam #### Parameters -| Name | Type | Description | -| ------- | --------------- | ----------- | -| version | `EnumMember` | | -| oldName | `scalar string` | | +| Name | Type | Description | +| ------- | --------------- | ------------------------------------------- | +| version | `EnumMember` | The version that the target was renamed in. | +| oldName | `scalar string` | The previous name of the target. | ### `@typeChangedFrom` {#@TypeSpec.Versioning.typeChangedFrom} @@ -95,10 +95,10 @@ dec TypeSpec.Versioning.typeChangedFrom(target: unknown, version: EnumMember, ol #### Parameters -| Name | Type | Description | -| ------- | --------------------- | ----------- | -| version | `EnumMember` | | -| oldType | `(intrinsic) unknown` | | +| Name | Type | Description | +| ------- | --------------------- | -------------------------------------------- | +| version | `EnumMember` | The version that the target type changed in. | +| oldType | `(intrinsic) unknown` | The previous type of the target. | ### `@useDependency` {#@TypeSpec.Versioning.useDependency} @@ -114,9 +114,9 @@ dec TypeSpec.Versioning.useDependency(target: EnumMember | Namespace, ...version #### Parameters -| Name | Type | Description | -| -------------- | -------------------- | ----------- | -| versionRecords | `model EnumMember[]` | | +| Name | Type | Description | +| -------------- | -------------------- | --------------------------------------------------------------------- | +| versionRecords | `model EnumMember[]` | The dependent library version(s) for the target namespace or version. | ### `@versioned` {#@TypeSpec.Versioning.versioned} @@ -132,6 +132,6 @@ dec TypeSpec.Versioning.versioned(target: Namespace, versions: Enum) #### Parameters -| Name | Type | Description | -| -------- | ------ | ----------- | -| versions | `Enum` | | +| Name | Type | Description | +| -------- | ------ | ----------------------------------------------- | +| versions | `Enum` | The enum that describes the supported versions. | diff --git a/packages/compiler/lib/decorators.ts b/packages/compiler/lib/decorators.ts index ccdb64b89da..2593aead0d6 100644 --- a/packages/compiler/lib/decorators.ts +++ b/packages/compiler/lib/decorators.ts @@ -821,15 +821,6 @@ export function getKeyName(program: Program, property: ModelProperty): string { return program.stateMap(keyKey).get(property); } -/** - * `@withDefaultKeyVisibility` - set the visibility of key properties in a model if not already set - * - * The first argument accepts a string representing the desired default - * visibility value. If a key property already has a `visibility` decorator - * then the default visibility is not applied. - * - * `@withDefaultKeyVisibility` can only be applied to model types. - */ export function $withDefaultKeyVisibility( context: DecoratorContext, entity: Model, diff --git a/packages/compiler/lib/decorators.tsp b/packages/compiler/lib/decorators.tsp index 24123157f90..7c5df6adf13 100644 --- a/packages/compiler/lib/decorators.tsp +++ b/packages/compiler/lib/decorators.tsp @@ -242,7 +242,7 @@ extern dec tag(target: Namespace | Interface | Operation, tag: string); /** * Specifies how a templated type should name their instances. * @param name name the template instance should take - * @formatArgs Model with key value used to interpolate the name + * @param formatArgs Model with key value used to interpolate the name * * @example * ```typespec @@ -274,6 +274,7 @@ extern dec knownValues(target: string | numeric | ModelProperty, values: Enum); /** * Mark a model property as the key to identify instances of that type + * @param altName Name of the property. If not specified, the decorated property name is used. * * @example * ```typespec @@ -316,6 +317,7 @@ extern dec projectedName(target: unknown, targetName: string, projectedName: str /** * Specify the property to be used to discriminate this type. + * @param propertyName The property name to use for discrimination * * @example * @@ -354,6 +356,8 @@ extern dec discriminator(target: Model | Union, propertyName: string); * * See also: [Automatic visibility](https://microsoft.github.io/typespec/standard-library/rest/operations#automatic-visibility) * + * @param visibilities List of visibilities which apply to this property. + * * @example * * ```typespec @@ -380,6 +384,8 @@ extern dec visibility(target: ModelProperty, ...visibilities: string[]); * When using an emitter that applies visibility automatically, it is generally * not necessary to use this decorator. * + * @param visibilities List of visibilities which apply to this property. + * * @example * ```typespec * model Dog { @@ -408,13 +414,42 @@ extern dec visibility(target: ModelProperty, ...visibilities: string[]); * ``` */ extern dec withVisibility(target: Model, ...visibilities: string[]); + +/** + * Set the visibility of key properties in a model if not already set. + * + * @param visibility The desired default visibility value. If a key property already has a `visibility` decorator then the default visibility is not applied. + */ extern dec withDefaultKeyVisibility(target: Model, visibility: unknown); + +/** + * Returns the model with non-updateable properties removed. + */ extern dec withUpdateableProperties(target: Model); + +/** + * Returns the model with any default values removed. + */ extern dec withoutDefaultValues(target: Model); + +/** + * Returns the model with the given properties omitted. + * @param omit List of properties to omit + */ extern dec withoutOmittedProperties(target: Model, omit: string | Union); //--------------------------------------------------------------------------- // Debugging //--------------------------------------------------------------------------- + +/** + * A debugging decorator used to inspect a type. + * @param text Custom text to log + */ extern dec inspectType(target: unknown, text: string); + +/** + * A debugging decorator used to inspect a type name. + * @param text Custom text to log + */ extern dec inspectTypeName(target: unknown, text: string); diff --git a/packages/compiler/lib/lib.tsp b/packages/compiler/lib/lib.tsp index 75d4520d0a2..b6d1cbfe6a2 100644 --- a/packages/compiler/lib/lib.tsp +++ b/packages/compiler/lib/lib.tsp @@ -117,12 +117,14 @@ model object {} /** * Array model type, equivalent to `T[]` + * @template T The type of the array elements */ @indexer(integer, T) model Array {} /** * Model with string properties where all the properties have type `T` + * @template T The type of the properties */ @indexer(string, T) model Record {} @@ -133,29 +135,51 @@ model Record {} @format("url") scalar url extends string; +/** + * Represents a collection of optional properties. + * @template T An object whose spread properties are all optional. + */ @doc("The template for adding optional properties.") @withOptionalProperties model OptionalProperties { ...T; } +/** + * Represents a collection of updateable properties. + * @template T An object whose spread properties are all updateable. + */ @doc("The template for adding updateable properties.") @withUpdateableProperties model UpdateableProperties { ...T; } +/** + * Represents a collection of omitted properties. + * @template T An object whose properties are spread. + * @template TKeys The property keys to omit. + */ @doc("The template for omitting properties.") @withoutOmittedProperties(TKeys) model OmitProperties { ...T; } +/** + * Represents a collection of properties with default values omitted. + * @template T An object whose spread property defaults are all omitted. + */ @withoutDefaultValues model OmitDefaults { ...T; } +/** + * Applies a visiblity setting to a collection of properties. + * @template T An object whose properties are spread. + * @template Visibility The visibility to apply to all properties. + */ @doc("The template for setting the default visibility of key properties.") @withDefaultKeyVisibility(Visibility) model DefaultKeyVisibility { diff --git a/packages/http/lib/auth.tsp b/packages/http/lib/auth.tsp index ee97898deae..8395ce4c780 100644 --- a/packages/http/lib/auth.tsp +++ b/packages/http/lib/auth.tsp @@ -61,6 +61,7 @@ enum ApiKeyLocation { /** * An API key is a token that a client provides when making API calls. The key can be sent in the query string: + * * ``` * GET /something?api_key=abcdef12345 * ``` @@ -78,6 +79,9 @@ enum ApiKeyLocation { * GET /something HTTP/1.1 * Cookie: X-API-KEY=abcdef12345 * ``` + * + * @template TLocation The location of the API key + * @template TName The name of the API key */ model ApiKeyAuth { @doc("API key authentication") @@ -95,6 +99,7 @@ model ApiKeyAuth { * OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials. * For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner. * For more information about OAuth 2.0, see oauth.net and RFC 6749. + * @template TFlows The list of supported OAuth2 flows */ model OAuth2Auth { @doc("OAuth2 authentication") diff --git a/packages/http/lib/http-decorators.tsp b/packages/http/lib/http-decorators.tsp index 61da390f27f..b8cc3ed2608 100644 --- a/packages/http/lib/http-decorators.tsp +++ b/packages/http/lib/http-decorators.tsp @@ -202,6 +202,7 @@ extern dec useAuth(target: Namespace, auth: object | Union | object[]); /** * Specify if inapplicable metadata should be included in the payload for the given entity. + * @param value If true, inapplicable metadata will be included in the payload. */ extern dec includeInapplicableMetadataInPayload(target: unknown, value: boolean); @@ -215,7 +216,7 @@ extern dec includeInapplicableMetadataInPayload(target: unknown, value: boolean) * `@route` can only be applied to operations, namespaces, and interfaces. * * @param path Relative route path. Cannot include query parameters. - * @param parameters Optional set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. + * @param options Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. * * @example * diff --git a/packages/http/lib/http.tsp b/packages/http/lib/http.tsp index d25ec72fb93..ac44ea6032d 100644 --- a/packages/http/lib/http.tsp +++ b/packages/http/lib/http.tsp @@ -30,6 +30,9 @@ model Body { body: T; } +/** + * The Location header contains the URL where the status of the long running operation can be checked. + */ model LocationHeader { @doc("The Location header contains the URL where the status of the long running operation can be checked.") @header @@ -40,18 +43,52 @@ model LocationHeader { // to update the default descriptions for these status codes. This ensures // that we get consistent emit between different ways to spell the same // responses in TypeSpec. + +/** + * The request has succeeded. + */ model OkResponse is Response<200>; +/** + * The request has succeeded and a new resource has been created as a result. + */ model CreatedResponse is Response<201>; +/** + * The request has been accepted for processing, but processing has not yet completed. + */ model AcceptedResponse is Response<202>; +/** + * There is no content to send for this request, but the headers may be useful. + */ model NoContentResponse is Response<204>; +/** + * The URL of the requested resource has been changed permanently. The new URL is given in the response. + */ model MovedResponse is Response<301> { ...LocationHeader; } +/** + * The client has made a conditional request and the resource has not been modified. + */ model NotModifiedResponse is Response<304>; +/** + * The server could not understand the request due to invalid syntax. + */ model BadRequestResponse is Response<400>; +/** + * Access is unauthorized. + */ model UnauthorizedResponse is Response<401>; +/** + * Access is forbidden. + */ model ForbiddenResponse is Response<403>; +/** + * The server cannot find the requested resource. + */ model NotFoundResponse is Response<404>; +/** + * The request conflicts with the current state of the server. + */ model ConflictResponse is Response<409>; /** diff --git a/packages/protobuf/test/scenarios.spec.ts b/packages/protobuf/test/scenarios.test.ts similarity index 100% rename from packages/protobuf/test/scenarios.spec.ts rename to packages/protobuf/test/scenarios.test.ts diff --git a/packages/protobuf/test/scenarios/array-nested/diagnostics.txt b/packages/protobuf/test/scenarios/array-nested/diagnostics.txt index 0c41dca15b1..2902e5342e1 100644 --- a/packages/protobuf/test/scenarios/array-nested/diagnostics.txt +++ b/packages/protobuf/test/scenarios/array-nested/diagnostics.txt @@ -1 +1 @@ -/test/.tsp/lib/lib.tsp:121:1 - error @typespec/protobuf/nested-array: nested arrays are not supported by the Protobuf emitter \ No newline at end of file +/test/.tsp/lib/lib.tsp:122:1 - error @typespec/protobuf/nested-array: nested arrays are not supported by the Protobuf emitter \ No newline at end of file diff --git a/packages/ref-doc/src/emitters/docusaurus.ts b/packages/ref-doc/src/emitters/docusaurus.ts index 1c13b02d454..9fc54b71ae4 100644 --- a/packages/ref-doc/src/emitters/docusaurus.ts +++ b/packages/ref-doc/src/emitters/docusaurus.ts @@ -6,6 +6,7 @@ import { ModelRefDoc, NamespaceRefDoc, OperationRefDoc, + ScalarRefDoc, TemplateParameterRefDoc, TypeSpecRefDoc, UnionRefDoc, @@ -268,7 +269,12 @@ function renderDataTypes(refDoc: TypeSpecRefDoc): string | undefined { content.push( groupByNamespace(refDoc.namespaces, (namespace) => { - if (namespace.models.length === 0) { + const modelCount = + namespace.models.length + + namespace.enums.length + + namespace.unions.length + + namespace.scalars.length; + if (modelCount === 0) { return undefined; } const content = []; @@ -281,6 +287,9 @@ function renderDataTypes(refDoc: TypeSpecRefDoc): string | undefined { for (const union of namespace.unions) { content.push(renderUnion(union), ""); } + for (const scalar of namespace.scalars) { + content.push(renderScalar(scalar), ""); + } return content.join("\n"); }) ); @@ -315,6 +324,7 @@ function renderEnum(e: EnumRefDoc, headingLevel: number = 3): string { return content.join("\n"); } + function renderUnion(union: UnionRefDoc, headingLevel: number = 3): string { const content = [ headings.hx(headingLevel, `${inlinecode(union.name)} {#${union.id}}`), @@ -331,6 +341,22 @@ function renderUnion(union: UnionRefDoc, headingLevel: number = 3): string { return content.join("\n"); } +function renderScalar(scalar: ScalarRefDoc, headingLevel: number = 3): string { + const content = [ + headings.hx(headingLevel, `${inlinecode(scalar.name)} {#${scalar.id}}`), + "", + scalar.doc, + codeblock(scalar.signature, "typespec"), + "", + ]; + + if (scalar.templateParameters) { + content.push(renderTemplateParametersTable(scalar.templateParameters, headingLevel + 1)); + } + + return content.join("\n"); +} + function groupByNamespace( namespaces: NamespaceRefDoc[], callback: (namespace: NamespaceRefDoc) => string | undefined diff --git a/packages/ref-doc/src/experimental.ts b/packages/ref-doc/src/experimental.ts index 7a7b56ccafb..cd75a87ea19 100644 --- a/packages/ref-doc/src/experimental.ts +++ b/packages/ref-doc/src/experimental.ts @@ -1,4 +1,11 @@ -import { compile, joinPaths, NodeHost, NodePackage } from "@typespec/compiler"; +import { + compile, + createDiagnosticCollector, + Diagnostic, + joinPaths, + NodeHost, + NodePackage, +} from "@typespec/compiler"; import { mkdir, readFile, writeFile } from "fs/promises"; import { generateJsApiDocs } from "./api-docs.js"; import { renderToDocusaurusMarkdown } from "./emitters/docusaurus.js"; @@ -12,7 +19,8 @@ export async function generateLibraryDocs( libraryPath: string, namespaces: string[], outputDir: string -) { +): Promise { + const diagnostics = createDiagnosticCollector(); const pkgJson = await readPackageJson(libraryPath); if (pkgJson.tspMain) { const main = joinPaths(libraryPath, pkgJson.tspMain); @@ -20,6 +28,9 @@ export async function generateLibraryDocs( parseOptions: { comments: true, docs: true }, }); const refDoc = extractRefDocs(program, namespaces); + for (const diag of program.diagnostics ?? []) { + diagnostics.add(diag); + } const files = renderToDocusaurusMarkdown(refDoc); await mkdir(outputDir, { recursive: true }); for (const [name, content] of Object.entries(files)) { @@ -29,19 +40,25 @@ export async function generateLibraryDocs( if (pkgJson.main) { await generateJsApiDocs(libraryPath, joinPaths(outputDir, "js-api")); } + return diagnostics.diagnostics; } export async function resolveLibraryRefDocs( libraryPath: string, namespaces: string[] -): Promise { +): Promise<[TypeSpecRefDoc, readonly Diagnostic[]] | undefined> { + const diagnostics = createDiagnosticCollector(); const pkgJson = await readPackageJson(libraryPath); if (pkgJson.tspMain) { const main = joinPaths(libraryPath, pkgJson.tspMain); const program = await compile(NodeHost, main, { parseOptions: { comments: true, docs: true }, }); - return extractRefDocs(program, namespaces); + const refDoc = extractRefDocs(program, namespaces); + for (const diag of program.diagnostics ?? []) { + diagnostics.add(diag); + } + return diagnostics.wrap(refDoc); } return undefined; } diff --git a/packages/ref-doc/src/extractor.ts b/packages/ref-doc/src/extractor.ts index aad3e950728..91daa9bda18 100644 --- a/packages/ref-doc/src/extractor.ts +++ b/packages/ref-doc/src/extractor.ts @@ -13,13 +13,16 @@ import { Model, Namespace, navigateTypesInNamespace, + NoTarget, Operation, Program, + Scalar, SyntaxKind, TemplatedType, Type, Union, } from "@typespec/compiler"; +import { reportDiagnostic } from "./lib.js"; import { DecoratorRefDoc, EnumRefDoc, @@ -29,6 +32,7 @@ import { ModelRefDoc, NamespaceRefDoc, OperationRefDoc, + ScalarRefDoc, TypeSpecRefDoc, UnionRefDoc, } from "./types.js"; @@ -52,6 +56,7 @@ export function extractRefDocs(program: Program, filterToNamespace: string[] = [ models: [], enums: [], unions: [], + scalars: [], }; refDoc.namespaces.push(namespaceDoc); navigateTypesInNamespace( @@ -82,6 +87,9 @@ export function extractRefDocs(program: Program, filterToNamespace: string[] = [ namespaceDoc.unions.push(extractUnionRefDocs(program, union as any)); } }, + scalar(scalar) { + namespaceDoc.scalars.push(extractScalarRefDocs(program, scalar as any)); + }, }, { includeTemplateDeclaration: true, skipSubNamespaces: true } ); @@ -95,6 +103,7 @@ export function extractRefDocs(program: Program, filterToNamespace: string[] = [ sort(namespace.models); sort(namespace.operations); sort(namespace.unions); + sort(namespace.scalars); } function sort(arr: { id: string }[]) { @@ -104,38 +113,67 @@ export function extractRefDocs(program: Program, filterToNamespace: string[] = [ return refDoc; } -function extractTemplateParameterDocs(type: TemplatedType) { +function extractTemplateParameterDocs(program: Program, type: TemplatedType) { if (isTemplateDeclaration(type)) { const templateParamsDocs = getTemplateParameterDocs(type); - return type.node!.templateParameters.map((x) => ({ - name: x.id.sv, - doc: templateParamsDocs.get(x.id.sv) ?? "", - })); + return type.node!.templateParameters.map((x) => { + const doc = templateParamsDocs.get(x.id.sv); + if (doc === undefined || doc === "") { + reportDiagnostic(program, { + code: "documentation-missing", + messageId: "templateParam", + format: { name: type.name ?? "", param: x.id.sv }, + target: NoTarget, + }); + } + return { + name: x.id.sv, + doc: templateParamsDocs.get(x.id.sv) ?? "", + }; + }); } else { return undefined; } } function extractInterfaceRefDocs(program: Program, iface: Interface): InterfaceRefDoc { + const doc = extractMainDoc(program, iface); + if (doc === undefined || doc === "") { + reportDiagnostic(program, { + code: "documentation-missing", + messageId: "interface", + format: { name: iface.name ?? "" }, + target: NoTarget, + }); + } return { id: getNamedTypeId(iface), name: iface.name, signature: getTypeSignature(iface), type: iface, - templateParameters: extractTemplateParameterDocs(iface), - doc: extractMainDoc(program, iface), + templateParameters: extractTemplateParameterDocs(program, iface), + doc: doc, examples: extractExamples(iface), }; } function extractOperationRefDoc(program: Program, operation: Operation): OperationRefDoc { + const doc = extractMainDoc(program, operation); + if (doc === undefined || doc === "") { + reportDiagnostic(program, { + code: "documentation-missing", + messageId: "operation", + format: { name: operation.name ?? "" }, + target: NoTarget, + }); + } return { id: getNamedTypeId(operation), name: operation.name, signature: getTypeSignature(operation), type: operation, - templateParameters: extractTemplateParameterDocs(operation), - doc: extractMainDoc(program, operation), + templateParameters: extractTemplateParameterDocs(program, operation), + doc: doc, examples: extractExamples(operation), }; } @@ -143,6 +181,15 @@ function extractOperationRefDoc(program: Program, operation: Operation): Operati function extractDecoratorRefDoc(program: Program, decorator: Decorator): DecoratorRefDoc { const paramDoc = getParmeterDocs(decorator); const parameters: FunctionParameterRefDoc[] = decorator.parameters.map((x) => { + const docVal = paramDoc.get(x.name); + if (docVal === undefined || docVal === "") { + reportDiagnostic(program, { + code: "documentation-missing", + messageId: "decoratorParam", + format: { name: decorator.name, param: x.name }, + target: NoTarget, + }); + } return { type: x, doc: paramDoc.get(x.name) ?? "", @@ -153,12 +200,21 @@ function extractDecoratorRefDoc(program: Program, decorator: Decorator): Decorat }); const examples = extractExamples(decorator); + const mainDoc = extractMainDoc(program, decorator); + if (mainDoc === undefined || mainDoc === "") { + reportDiagnostic(program, { + code: "documentation-missing", + messageId: "decorator", + format: { name: decorator.name }, + target: NoTarget, + }); + } return { id: getNamedTypeId(decorator), name: decorator.name, type: decorator, signature: getTypeSignature(decorator), - doc: extractMainDoc(program, decorator), + doc: mainDoc, parameters, examples, otherTags: [], @@ -173,35 +229,82 @@ function extractDecoratorRefDoc(program: Program, decorator: Decorator): Decorat } function extractModelRefDocs(program: Program, type: Model): ModelRefDoc { + const doc = extractMainDoc(program, type); + if (doc === undefined || doc === "") { + reportDiagnostic(program, { + code: "documentation-missing", + messageId: "model", + format: { name: type.name ?? "" }, + target: NoTarget, + }); + } return { id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), type, - templateParameters: extractTemplateParameterDocs(type), - doc: extractMainDoc(program, type), + templateParameters: extractTemplateParameterDocs(program, type), + doc: doc, examples: extractExamples(type), }; } function extractEnumRefDoc(program: Program, type: Enum): EnumRefDoc { + const doc = extractMainDoc(program, type); + if (doc === undefined || doc === "") { + reportDiagnostic(program, { + code: "documentation-missing", + messageId: "enum", + format: { name: type.name ?? "" }, + target: NoTarget, + }); + } return { id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), type, - doc: extractMainDoc(program, type), + doc: doc, examples: extractExamples(type), }; } function extractUnionRefDocs(program: Program, type: Union & { name: string }): UnionRefDoc { + const doc = extractMainDoc(program, type); + if (doc === undefined || doc === "") { + reportDiagnostic(program, { + code: "documentation-missing", + messageId: "union", + format: { name: type.name ?? "" }, + target: NoTarget, + }); + } + return { + id: getNamedTypeId(type), + name: type.name, + signature: getTypeSignature(type), + type, + templateParameters: extractTemplateParameterDocs(program, type), + doc: doc, + examples: extractExamples(type), + }; +} + +function extractScalarRefDocs(program: Program, type: Scalar): ScalarRefDoc { + const doc = extractMainDoc(program, type); + if (doc === undefined || doc === "") { + reportDiagnostic(program, { + code: "documentation-missing", + messageId: "scalar", + format: { name: type.name ?? "" }, + target: NoTarget, + }); + } return { id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), type, - templateParameters: extractTemplateParameterDocs(type), - doc: extractMainDoc(program, type), + doc: doc, examples: extractExamples(type), }; } diff --git a/packages/ref-doc/src/index.ts b/packages/ref-doc/src/index.ts index ee90713c8a5..28ba03ad006 100644 --- a/packages/ref-doc/src/index.ts +++ b/packages/ref-doc/src/index.ts @@ -1,3 +1,4 @@ export * from "./api-docs.js"; export * from "./experimental.js"; export * from "./extractor.js"; +export * from "./lib.js"; diff --git a/packages/ref-doc/src/lib.ts b/packages/ref-doc/src/lib.ts new file mode 100644 index 00000000000..7005b75a1c0 --- /dev/null +++ b/packages/ref-doc/src/lib.ts @@ -0,0 +1,26 @@ +import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler"; + +export const libDef = { + name: "@typespec/ref-doc", + diagnostics: { + "documentation-missing": { + severity: "warning", + messages: { + decorator: paramMessage`Missing documentation for decorator '${"name"}'.`, + decoratorParam: paramMessage`Missing documentation for decorator parameter '${"name"}.${"param"}'.`, + templateParam: paramMessage`Missing documentation for template parameter '${"name"}.${"param"}'.`, + model: paramMessage`Missing documentation for model '${"name"}'.`, + union: paramMessage`Missing documentation for union '${"name"}'.`, + enum: paramMessage`Missing documentation for enum '${"name"}'.`, + interface: paramMessage`Missing documentation for interface '${"name"}'.`, + operation: paramMessage`Missing documentation for operation '${"name"}'.`, + scalar: paramMessage`Missing documentation for scalar '${"name"}'.`, + }, + }, + }, +} as const; + +export const $lib = createTypeSpecLibrary(libDef); +export const { reportDiagnostic, createStateSymbol } = $lib; + +export type RefDocLibrary = typeof $lib; diff --git a/packages/ref-doc/src/types.ts b/packages/ref-doc/src/types.ts index 32c3bedb20e..b09543db424 100644 --- a/packages/ref-doc/src/types.ts +++ b/packages/ref-doc/src/types.ts @@ -5,6 +5,7 @@ import { Interface, Model, Operation, + Scalar, Union, } from "@typespec/compiler"; @@ -20,6 +21,7 @@ export type NamespaceRefDoc = { models: ModelRefDoc[]; enums: EnumRefDoc[]; unions: UnionRefDoc[]; + scalars: ScalarRefDoc[]; }; export type NamedTypeRefDoc = { @@ -85,3 +87,9 @@ export type UnionRefDoc = NamedTypeRefDoc & { templateParameters?: TemplateParameterRefDoc[]; }; + +export type ScalarRefDoc = NamedTypeRefDoc & { + type: Scalar; + + templateParameters?: TemplateParameterRefDoc[]; +}; diff --git a/packages/rest/lib/resource.tsp b/packages/rest/lib/resource.tsp index dbc9c9185c4..34b11143ed1 100644 --- a/packages/rest/lib/resource.tsp +++ b/packages/rest/lib/resource.tsp @@ -15,21 +15,37 @@ model ResourceError { message: string; } +/** + * Dynamically gathers keys of the model type T. + * @template T The target model. + */ @doc("Dynamically gathers keys of the model type T.") @copyResourceKeyParameters @friendlyName("{name}Key", T) model KeysOf {} +/** + * Dynamically gathers parent keys of the model type T. + * @template T The target model. + */ @doc("Dynamically gathers parent keys of the model type T.") @copyResourceKeyParameters("parent") @friendlyName("{name}ParentKey", T) model ParentKeysOf {} +/** + * Represents operation parameters for resource TResource. + * @template TResource The resource model. + */ @doc("Represents operation parameters for resource TResource.") model ResourceParameters { ...KeysOf; } +/** + * Represents collection operation parameters for resource TResource. + * @template TResource The resource model. + */ @doc("Represents collection operation parameters for resource TResource.") model ResourceCollectionParameters { ...ParentKeysOf; @@ -49,12 +65,21 @@ interface ResourceRead { get(...ResourceParameters): TResource | TError; } +/** + * Resource create operation completed successfully. + * @template T The resource model that was created. + */ @doc("Resource create operation completed successfully.") model ResourceCreatedResponse { ...CreatedResponse; @body body: T; } +/** + * Resource create or replace operation template. + * @template TResource The resource model to create or replace. + * @template TError The error response. + */ interface ResourceCreateOrReplace { @autoRoute @doc("Creates or replaces a instance of the resource.") @@ -65,10 +90,19 @@ interface ResourceCreateOrReplace { ): TResource | ResourceCreatedResponse | TError; } +/** + * Resource create or update operation model. + * @template TResource The resource model to create or update. + */ @friendlyName("{name}Update", TResource) model ResourceCreateOrUpdateModel is OptionalProperties>>; +/** + * Resource create or update operation template. + * @template TResource The resource model to create or update. + * @template TError The error response. + */ interface ResourceCreateOrUpdate { @autoRoute @doc("Creates or update a instance of the resource.") @@ -79,10 +113,19 @@ interface ResourceCreateOrUpdate { ): TResource | ResourceCreatedResponse | TError; } +/** + * Resource create operation model. + * @template TResource The resource model to create. + */ @friendlyName("{name}Create", TResource) model ResourceCreateModel is UpdateableProperties>; +/** + * Resource create operation template. + * @template TResource The resource model to create. + * @template TError The error response. + */ interface ResourceCreate { @autoRoute @doc("Creates a new instance of the resource.") @@ -93,6 +136,11 @@ interface ResourceCreate { ): TResource | ResourceCreatedResponse | TError; } +/** + * Resource update operation template. + * @template TResource The resource model to update. + * @template TError The error response. + */ @Private.validateHasKey(TResource) @Private.validateIsError(TError) interface ResourceUpdate { @@ -112,6 +160,11 @@ model ResourceDeletedResponse { _: 200; } +/** + * Resource delete operation template. + * @template TResource The resource model to delete. + * @template TError The error response. + */ @Private.validateHasKey(TResource) @Private.validateIsError(TError) interface ResourceDelete { @@ -125,6 +178,7 @@ interface ResourceDelete { * Structure for a paging response using `value` and `nextLink` to represent pagination. * This only provides the model structure and not actual pagination support. * See https://github.com/microsoft/typespec/issues/705 for general paging support. + * @template T The resource type of the collection. */ @doc("Paged response of {name} items", T) @friendlyName("{name}CollectionWithNextLink", T) @@ -136,6 +190,11 @@ model CollectionWithNextLink { nextLink?: ResourceLocation; } +/** + * Resource list operation template. + * @template TResource The resource model to list. + * @template TError The error response. + */ interface ResourceList { @autoRoute @doc("Lists all instances of the resource.") @@ -143,6 +202,11 @@ interface ResourceList { list(...ResourceCollectionParameters): CollectionWithNextLink | TError; } +/** + * Resource operation templates for resource instances. + * @template TResource The resource model. + * @template TError The error response. + */ @Private.validateHasKey(TResource) @Private.validateIsError(TError) interface ResourceInstanceOperations @@ -150,18 +214,34 @@ interface ResourceInstanceOperations ResourceUpdate, ResourceDelete {} +/** + * Resource operation templates for resource collections. + * @template TResource The resource model. + * @template TError The error response. + */ @Private.validateHasKey(TResource) @Private.validateIsError(TError) interface ResourceCollectionOperations extends ResourceCreate, ResourceList {} +/** + * Resource operation templates for resources. + * @template TResource The resource model. + * @template TError The error response. + */ @Private.validateHasKey(TResource) @Private.validateIsError(TError) interface ResourceOperations extends ResourceInstanceOperations, ResourceCollectionOperations {} +/** + * Singleton resource read operation template. + * @template TSingleton The singleton resource model. + * @template TResource The resource model. + * @template TError The error response. + */ @Private.validateHasKey(TResource) @Private.validateIsError(TError) interface SingletonResourceRead { @@ -172,6 +252,12 @@ interface SingletonResourceRead): TSingleton | TError; } +/** + * Singleton resource update operation template. + * @template TSingleton The singleton resource model. + * @template TResource The resource model. + * @template TError The error response. + */ @Private.validateHasKey(TResource) @Private.validateIsError(TError) interface SingletonResourceUpdate { @@ -187,10 +273,22 @@ interface SingletonResourceUpdate extends SingletonResourceRead, SingletonResourceUpdate {} +/** + * Extension resource read operation template. + * @template TExtension The extension resource model. + * @template TResource The resource model. + * @template TError The error response. + */ @Private.validateHasKey(TResource) @Private.validateIsError(TError) interface ExtensionResourceRead { @@ -200,6 +298,12 @@ interface ExtensionResourceRead, ...ResourceParameters): TExtension | TError; } +/** + * Extension resource create or update operation template. + * @template TExtension The extension resource model. + * @template TResource The resource model. + * @template TError The error response. + */ interface ExtensionResourceCreateOrUpdate< TExtension extends object, TResource extends object, @@ -215,6 +319,12 @@ interface ExtensionResourceCreateOrUpdate< ): TExtension | ResourceCreatedResponse | TError; } +/** + * Extension resource create operation template. + * @template TExtension The extension resource model. + * @template TResource The resource model. + * @template TError The error response. + */ interface ExtensionResourceCreate { @autoRoute @doc("Creates a new instance of the extension resource.") @@ -225,6 +335,12 @@ interface ExtensionResourceCreate | TError; } +/** + * Extension resource update operation template. + * @template TExtension The extension resource model. + * @template TResource The resource model. + * @template TError The error response. + */ interface ExtensionResourceUpdate { @autoRoute @doc("Updates an existing instance of the extension resource.") @@ -238,6 +354,12 @@ interface ExtensionResourceUpdate { @autoRoute @doc("Deletes an existing instance of the extension resource.") @@ -248,6 +370,12 @@ interface ExtensionResourceDelete { @autoRoute @doc("Lists all instances of the extension resource.") @@ -258,6 +386,12 @@ interface ExtensionResourceList | TError; } +/** + * Extension resource operation templates for extension resource instances. + * @template TExtension The extension resource model. + * @template TResource The resource model. + * @template TError The error response. + */ interface ExtensionResourceInstanceOperations< TExtension extends object, TResource extends object, @@ -267,6 +401,12 @@ interface ExtensionResourceInstanceOperations< ExtensionResourceUpdate, ExtensionResourceDelete {} +/** + * Extension resource operation templates for extension resource collections. + * @template TExtension The extension resource model. + * @template TResource The resource model. + * @template TError The error response. + */ interface ExtensionResourceCollectionOperations< TExtension extends object, TResource extends object, @@ -275,6 +415,12 @@ interface ExtensionResourceCollectionOperations< extends ExtensionResourceCreate, ExtensionResourceList {} +/** + * Extension resource operation templates for extension resource instances and collections. + * @template TExtension The extension resource model. + * @template TResource The resource model. + * @template TError The error response. + */ interface ExtensionResourceOperations extends ExtensionResourceInstanceOperations, ExtensionResourceCollectionOperations {} diff --git a/packages/rest/lib/rest-decorators.tsp b/packages/rest/lib/rest-decorators.tsp index c86b4368f76..f82d246d547 100644 --- a/packages/rest/lib/rest-decorators.tsp +++ b/packages/rest/lib/rest-decorators.tsp @@ -31,6 +31,7 @@ extern dec segment(target: Model | ModelProperty | Operation, name: string); /** * Returns the URL segment of a given model if it has `@segment` and `@key` decorator. + * @param type Target model */ extern dec segmentOf(target: Operation, type: Model); @@ -51,59 +52,62 @@ extern dec resource(target: Model, collectionName: string); /** * Specify that this is a Read operation for a given resource. * - * @param resource Resource marked with @resource + * @param resourceType Resource marked with @resource */ extern dec readsResource(target: Operation, resourceType: Model); /** * Specify that this is a Create operation for a given resource. * - * @param resource Resource marked with @resource + * @param resourceType Resource marked with @resource */ extern dec createsResource(target: Operation, resourceType: Model); /** * Specify that this is a CreateOrReplace operation for a given resource. * - * @param resource Resource marked with @resource + * @param resourceType Resource marked with @resource */ extern dec createsOrReplacesResource(target: Operation, resourceType: Model); /** * Specify that this is a CreatesOrUpdate operation for a given resource. * - * @param resource Resource marked with @resource + * @param resourceType Resource marked with @resource */ extern dec createsOrUpdatesResource(target: Operation, resourceType: Model); /** * Specify that this is a Update operation for a given resource. * - * @param resource Resource marked with @resource + * @param resourceType Resource marked with @resource */ extern dec updatesResource(target: Operation, resourceType: Model); /** * Specify that this is a Delete operation for a given resource. * - * @param resource Resource marked with @resource + * @param resourceType Resource marked with @resource */ extern dec deletesResource(target: Operation, resourceType: Model); /** * Specify that this is a List operation for a given resource. * - * @param resource Resource marked with @resource + * @param resourceType Resource marked with @resource */ extern dec listsResource(target: Operation, resourceType: Model); /** - * Specify this operation is an action. (Scopped to a resource item /pets/{petId}/my-action) + * Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my-action) + * @param name Name of the action. If not specified, the name of the operation will be used. */ extern dec action(target: Operation, name?: string); /** * Specify this operation is a collection action. (Scopped to a resource, /pets/my-action) + * @param resourceType Resource marked with @resource + * @param name Name of the action. If not specified, the name of the operation will be used. */ extern dec collectionAction(target: Operation, resourceType: Model, name?: string); diff --git a/packages/rest/lib/rest.tsp b/packages/rest/lib/rest.tsp index a7d997ceee9..2f300a364a6 100644 --- a/packages/rest/lib/rest.tsp +++ b/packages/rest/lib/rest.tsp @@ -4,6 +4,10 @@ import "./resource.tsp"; namespace TypeSpec.Rest; +/** + * A URL that points to a resource. + * @template TResource The type of resource that the URL points to. + */ @doc("The location of an instance of {name}", TResource) @Private.resourceLocation(TResource) scalar ResourceLocation extends url; diff --git a/packages/versioning/lib/decorators.tsp b/packages/versioning/lib/decorators.tsp index c173b81172b..d718c63fa17 100644 --- a/packages/versioning/lib/decorators.tsp +++ b/packages/versioning/lib/decorators.tsp @@ -6,56 +6,69 @@ namespace TypeSpec { namespace Versioning { /** * Identifies that the decorated namespace is versioned by the provided enum. + * @param versions The enum that describes the supported versions. */ extern dec versioned(target: Namespace, versions: Enum); /** * Identifies that a namespace or a given versioning enum member relies upon a versioned package. + * @param versionRecords The dependent library version(s) for the target namespace or version. */ extern dec useDependency(target: EnumMember | Namespace, ...versionRecords: EnumMember[]); /** * Identifies when the target was added. + * @param version The version that the target was added in. */ extern dec added(target: unknown, version: EnumMember); /** * Identifies when the target was removed. + * @param version The version that the target was removed in. */ extern dec removed(target: unknown, version: EnumMember); /** * Identifies when the target has been renamed. + * @param version The version that the target was renamed in. + * @param oldName The previous name of the target. */ extern dec renamedFrom(target: unknown, version: EnumMember, oldName: string); /** * Identifies when a target was made optional. + * @param version The version that the target was made optional in. */ extern dec madeOptional(target: unknown, version: EnumMember); /** * Identifies when the target type changed. + * @param version The version that the target type changed in. + * @param oldType The previous type of the target. */ extern dec typeChangedFrom(target: unknown, version: EnumMember, oldType: unknown); /** * Returns whether the target exists for the given version. + * @param version The version to check. */ extern fn existsAtVersion(target: unknown, version: EnumMember): boolean; /** * Returns whether the target has a different name for the given version. + * @param version The version to check. */ extern fn hasDifferentNameAtVersion(target: unknown, version: EnumMember): boolean; /** * Returns whether the target was made optional after the given version. + * @param version The version to check. */ extern fn madeOptionalAfter(target: unknown, version: EnumMember): boolean; /** * Returns whether the version exists for the provided enum member. + * @param version The version to check. */ extern fn getVersionForEnumMember(target: unknown, version: EnumMember): boolean; } diff --git a/packages/website/.scripts/regen-ref-docs.mjs b/packages/website/.scripts/regen-ref-docs.mjs index f763dfa192b..26963a63b52 100644 --- a/packages/website/.scripts/regen-ref-docs.mjs +++ b/packages/website/.scripts/regen-ref-docs.mjs @@ -1,5 +1,6 @@ #!/usr/bin/env node // @ts-check +import { NodeHost, logDiagnostics } from "@typespec/compiler"; import { generateJsApiDocs, generateLibraryDocs, resolveLibraryRefDocs } from "@typespec/ref-doc"; import { renderDecoratorFile } from "@typespec/ref-doc/emitters/docusaurus"; import assert from "assert"; @@ -9,52 +10,84 @@ import { fileURLToPath } from "url"; export const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../.."); +const diagnostics = new Map(); + // Compiler -await generateCompilerDocs(); +const compilerDiag = await generateCompilerDocs(); +if (compilerDiag.length) { + diagnostics.set("@typespec/compiler", compilerDiag); +} // Http -await generateLibraryDocs( +const httpDiag = await generateLibraryDocs( join(repoRoot, "packages/http"), ["TypeSpec.Http"], join(repoRoot, "docs/standard-library/http/reference") ); +if (httpDiag.length) { + diagnostics.set("@typespec/http", httpDiag); +} // Rest -await generateLibraryDocs( +const restDiag = await generateLibraryDocs( join(repoRoot, "packages/rest"), ["TypeSpec.Rest", "TypeSpec.Rest.Resource"], join(repoRoot, "docs/standard-library/rest/reference") ); +if (restDiag.length) { + diagnostics.set("@typespec/rest", restDiag); +} // OpenAPI -await generateLibraryDocs( +const openapiDiag = await generateLibraryDocs( join(repoRoot, "packages/openapi"), ["OpenAPI"], join(repoRoot, "docs/standard-library/openapi/reference") ); +if (openapiDiag.length) { + diagnostics.set("@typespec/openapi", openapiDiag); +} // Protobuf -await generateLibraryDocs( +const protobufDiag = await generateLibraryDocs( join(repoRoot, "packages/protobuf"), ["TypeSpec.Protobuf"], join(repoRoot, "docs/standard-library/protobuf/reference") ); +if (protobufDiag.length) { + diagnostics.set("@typespec/protobuf", protobufDiag); +} // Versioning -await generateLibraryDocs( +const versioningDiag = await generateLibraryDocs( join(repoRoot, "packages/versioning"), ["TypeSpec.Versioning"], join(repoRoot, "docs/standard-library/versioning/reference") ); +if (versioningDiag.length) { + diagnostics.set("@typespec/versioning", versioningDiag); +} + +let exitCode = 0; +// Log the diagnostics +for (const pkg of diagnostics.keys()) { + console.log(`\nIssues in ${pkg}:`); + const diags = diagnostics.get(pkg); + logDiagnostics(diags, NodeHost.logSink); + exitCode = 1; +} +process.exit(exitCode); async function generateCompilerDocs() { const compilerPath = join(repoRoot, "packages/compiler"); const outputDir = join(repoRoot, "docs/standard-library"); - const refDoc = await resolveLibraryRefDocs(compilerPath, ["TypeSpec"]); - assert(refDoc, "Unexpected ref doc should have been resolved for compiler."); + const results = await resolveLibraryRefDocs(compilerPath, ["TypeSpec"]); + assert(results, "Unexpected ref doc should have been resolved for compiler."); + const [refDoc, diagnostics] = results; const decoratorContent = renderDecoratorFile(refDoc, { title: "Built-in Decorators" }); assert(decoratorContent, "Unexpected decorator file shouldn't be empty for compiler."); await writeFile(join(outputDir, "built-in-decorators.md"), decoratorContent); await generateJsApiDocs(compilerPath, join(outputDir, "reference/js-api")); + return diagnostics; } diff --git a/packages/website/package.json b/packages/website/package.json index 0b07a78e807..e19265eb637 100644 --- a/packages/website/package.json +++ b/packages/website/package.json @@ -31,6 +31,7 @@ "react-dom": "^17.0.2" }, "devDependencies": { + "@typespec/compiler": "~0.43.0", "@typespec/ref-doc": "~0.1.0", "@typespec/spec": "0.1.0", "@typespec/http": "~0.43.1",