From 1c8de01ebe950377b8ecf161c706c36d6163c17b Mon Sep 17 00:00:00 2001 From: Will Temple Date: Thu, 30 Nov 2023 12:29:18 -0500 Subject: [PATCH 01/11] Rename template parameters for clarity. This removes the `T` prefix from most parameter names and reworks the names to be more indicative of what the parameters actually represent. This is in preparation for the introduction of named argument instantiation. --- docs/libraries/http/reference/data-types.md | 24 +- .../protobuf/reference/data-types.md | 10 +- docs/libraries/rest/reference/data-types.md | 69 +-- docs/libraries/rest/reference/interfaces.md | 320 +++++------ docs/standard-library/built-in-data-types.md | 30 +- packages/compiler/lib/lib.tsp | 55 +- packages/http/lib/auth.tsp | 10 +- packages/http/lib/http.tsp | 15 +- packages/protobuf/lib/proto.tsp | 6 +- packages/rest/lib/resource.tsp | 502 ++++++++++-------- packages/samples/specs/petstore/petstore.tsp | 8 +- .../samples/specs/signatures/signatures.tsp | 18 +- .../samples/specs/visibility/visibility.tsp | 12 +- 13 files changed, 566 insertions(+), 513 deletions(-) diff --git a/docs/libraries/http/reference/data-types.md b/docs/libraries/http/reference/data-types.md index d575a9d13d..d78317cca8 100644 --- a/docs/libraries/http/reference/data-types.md +++ b/docs/libraries/http/reference/data-types.md @@ -39,15 +39,15 @@ Cookie: X-API-KEY=abcdef12345 ``` ```typespec -model TypeSpec.Http.ApiKeyAuth +model TypeSpec.Http.ApiKeyAuth ``` #### Template Parameters -| Name | Description | -| --------- | --------------------------- | -| TLocation | The location of the API key | -| TName | The name of the API key | +| Name | Description | +| -------- | --------------------------- | +| Location | The location of the API key | +| Name | The name of the API key | ### `AuthorizationCodeFlow` {#TypeSpec.Http.AuthorizationCodeFlow} @@ -97,18 +97,18 @@ model TypeSpec.Http.BearerAuth Defines a model with a single property of the given type, marked with `@body`. -This can be useful in situations where you cannot use a bare T as the body +This can be useful in situations where you cannot use a bare type as the body and it is awkward to add a property. ```typespec -model TypeSpec.Http.Body +model TypeSpec.Http.Body ``` #### Template Parameters -| Name | Description | -| ---- | ---------------------------------------- | -| T | The type of the model's `body` property. | +| Name | Description | +| ----- | ---------------------------------------- | +| TBody | The type of the model's `body` property. | ### `ClientCredentialsFlow` {#TypeSpec.Http.ClientCredentialsFlow} @@ -237,14 +237,14 @@ Produces a new model with the same properties as T, but with `@query`, `@header`, `@body`, and `@path` decorators removed from all properties. ```typespec -model TypeSpec.Http.PlainData +model TypeSpec.Http.PlainData ``` #### Template Parameters | Name | Description | | ---- | -------------------------------------- | -| T | The model to spread as the plain data. | +| Data | The model to spread as the plain data. | ### `QueryOptions` {#TypeSpec.Http.QueryOptions} diff --git a/docs/libraries/protobuf/reference/data-types.md b/docs/libraries/protobuf/reference/data-types.md index a354895162..3c12f0f9f7 100644 --- a/docs/libraries/protobuf/reference/data-types.md +++ b/docs/libraries/protobuf/reference/data-types.md @@ -49,15 +49,15 @@ The key type of a Protobuf `map` must be any integral type or `string`. The valu another `Map`. ```typespec -model TypeSpec.Protobuf.Map +model TypeSpec.Protobuf.Map ``` #### Template Parameters -| Name | Description | -| ---- | ------------------------------------------------ | -| K | the key type (any integral type or string) | -| V | the value type (any type other than another map) | +| Name | Description | +| ----- | ------------------------------------------------ | +| Key | the key type (any integral type or string) | +| Value | the value type (any type other than another map) | ### `PackageDetails` {#TypeSpec.Protobuf.PackageDetails} diff --git a/docs/libraries/rest/reference/data-types.md b/docs/libraries/rest/reference/data-types.md index 5db8bbc42d..ef10617492 100644 --- a/docs/libraries/rest/reference/data-types.md +++ b/docs/libraries/rest/reference/data-types.md @@ -21,8 +21,9 @@ scalar TypeSpec.Rest.ResourceLocation ### `CollectionWithNextLink` {#TypeSpec.Rest.Resource.CollectionWithNextLink} 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. + +This only provides the model structure and not actual pagination support. See +https://github.com/microsoft/typespec/issues/705 for general paging support. ```typespec model TypeSpec.Rest.Resource.CollectionWithNextLink @@ -36,87 +37,87 @@ model TypeSpec.Rest.Resource.CollectionWithNextLink ### `KeysOf` {#TypeSpec.Rest.Resource.KeysOf} -Dynamically gathers keys of the model type T. +Dynamically gathers keys of the model type `Resource`. ```typespec -model TypeSpec.Rest.Resource.KeysOf +model TypeSpec.Rest.Resource.KeysOf ``` #### Template Parameters -| Name | Description | -| ---- | ----------------- | -| T | The target model. | +| Name | Description | +| -------- | -------------------------- | +| Resource | The target resource model. | ### `ParentKeysOf` {#TypeSpec.Rest.Resource.ParentKeysOf} -Dynamically gathers parent keys of the model type T. +Dynamically gathers parent keys of the model type `Resource`. ```typespec -model TypeSpec.Rest.Resource.ParentKeysOf +model TypeSpec.Rest.Resource.ParentKeysOf ``` #### Template Parameters -| Name | Description | -| ---- | ----------------- | -| T | The target model. | +| Name | Description | +| -------- | -------------------------- | +| Resource | The target resource model. | ### `ResourceCollectionParameters` {#TypeSpec.Rest.Resource.ResourceCollectionParameters} -Represents collection operation parameters for resource TResource. +Represents collection operation parameters for the resource of type `Resource`. ```typespec -model TypeSpec.Rest.Resource.ResourceCollectionParameters +model TypeSpec.Rest.Resource.ResourceCollectionParameters ``` #### Template Parameters -| Name | Description | -| --------- | ------------------- | -| TResource | The resource model. | +| Name | Description | +| -------- | ------------------- | +| Resource | The resource model. | ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} Resource create operation completed successfully. ```typespec -model TypeSpec.Rest.Resource.ResourceCreatedResponse +model TypeSpec.Rest.Resource.ResourceCreatedResponse ``` #### Template Parameters -| Name | Description | -| ---- | ------------------------------------ | -| T | The resource model that was created. | +| Name | Description | +| -------- | ------------------------------------ | +| Resource | The resource model that was created. | ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} Resource create operation model. ```typespec -model TypeSpec.Rest.Resource.ResourceCreateModel +model TypeSpec.Rest.Resource.ResourceCreateModel ``` #### Template Parameters -| Name | Description | -| --------- | ----------------------------- | -| TResource | The resource model to create. | +| Name | Description | +| -------- | ----------------------------- | +| Resource | The resource model to create. | ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} Resource create or update operation model. ```typespec -model TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel +model TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel ``` #### Template Parameters -| Name | Description | -| --------- | --------------------------------------- | -| TResource | The resource model to create or update. | +| Name | Description | +| -------- | --------------------------------------- | +| Resource | The resource model to create or update. | ### `ResourceDeletedResponse` {#TypeSpec.Rest.Resource.ResourceDeletedResponse} @@ -136,14 +137,14 @@ model TypeSpec.Rest.Resource.ResourceError ### `ResourceParameters` {#TypeSpec.Rest.Resource.ResourceParameters} -Represents operation parameters for resource TResource. +Represents operation parameters for the resource of type `Resource`. ```typespec -model TypeSpec.Rest.Resource.ResourceParameters +model TypeSpec.Rest.Resource.ResourceParameters ``` #### Template Parameters -| Name | Description | -| --------- | ------------------- | -| TResource | The resource model. | +| Name | Description | +| -------- | ------------------- | +| Resource | The resource model. | diff --git a/docs/libraries/rest/reference/interfaces.md b/docs/libraries/rest/reference/interfaces.md index ba064c720b..09077a31b1 100644 --- a/docs/libraries/rest/reference/interfaces.md +++ b/docs/libraries/rest/reference/interfaces.md @@ -13,23 +13,23 @@ toc_max_heading_level: 3 Extension resource operation templates for extension resource collections. ```typespec -interface TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations +interface TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TExtension | The extension resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Extension | The extension resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `ExtensionResourceCollectionOperations.create` {#TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.create} Creates a new instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): TExtension | TypeSpec.Rest.Resource.ResourceCreatedResponse | TError +op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): Extension | TypeSpec.Rest.Resource.ResourceCreatedResponse | Error ``` #### `ExtensionResourceCollectionOperations.list` {#TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.list} @@ -37,7 +37,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.create(resource: Lists all instances of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | TError +op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ExtensionResourceCreate` {#TypeSpec.Rest.Resource.ExtensionResourceCreate} @@ -45,23 +45,23 @@ op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.list(): TypeSpec Extension resource create operation template. ```typespec -interface TypeSpec.Rest.Resource.ExtensionResourceCreate +interface TypeSpec.Rest.Resource.ExtensionResourceCreate ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TExtension | The extension resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Extension | The extension resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `ExtensionResourceCreate.create` {#TypeSpec.Rest.Resource.ExtensionResourceCreate.create} Creates a new instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceCreate.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): TExtension | TypeSpec.Rest.Resource.ResourceCreatedResponse | TError +op TypeSpec.Rest.Resource.ExtensionResourceCreate.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): Extension | TypeSpec.Rest.Resource.ResourceCreatedResponse | Error ``` ### `ExtensionResourceCreateOrUpdate` {#TypeSpec.Rest.Resource.ExtensionResourceCreateOrUpdate} @@ -69,23 +69,23 @@ op TypeSpec.Rest.Resource.ExtensionResourceCreate.create(resource: TypeSpec.Rest Extension resource create or update operation template. ```typespec -interface TypeSpec.Rest.Resource.ExtensionResourceCreateOrUpdate +interface TypeSpec.Rest.Resource.ExtensionResourceCreateOrUpdate ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TExtension | The extension resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Extension | The extension resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `ExtensionResourceCreateOrUpdate.createOrUpdate` {#TypeSpec.Rest.Resource.ExtensionResourceCreateOrUpdate.createOrUpdate} Creates or update an instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceCreateOrUpdate.createOrUpdate(resource: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): TExtension | TypeSpec.Rest.Resource.ResourceCreatedResponse | TError +op TypeSpec.Rest.Resource.ExtensionResourceCreateOrUpdate.createOrUpdate(resource: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): Extension | TypeSpec.Rest.Resource.ResourceCreatedResponse | Error ``` ### `ExtensionResourceDelete` {#TypeSpec.Rest.Resource.ExtensionResourceDelete} @@ -93,23 +93,23 @@ op TypeSpec.Rest.Resource.ExtensionResourceCreateOrUpdate.createOrUpdate(resourc Extension resource delete operation template. ```typespec -interface TypeSpec.Rest.Resource.ExtensionResourceDelete +interface TypeSpec.Rest.Resource.ExtensionResourceDelete ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TExtension | The extension resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Extension | The extension resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `ExtensionResourceDelete.delete` {#TypeSpec.Rest.Resource.ExtensionResourceDelete.delete} Deletes an existing instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceDelete.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | TError +op TypeSpec.Rest.Resource.ExtensionResourceDelete.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | Error ``` ### `ExtensionResourceInstanceOperations` {#TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations} @@ -117,23 +117,23 @@ op TypeSpec.Rest.Resource.ExtensionResourceDelete.delete(): TypeSpec.Rest.Resour Extension resource operation templates for extension resource instances. ```typespec -interface TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations +interface TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TExtension | The extension resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Extension | The extension resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `ExtensionResourceInstanceOperations.get` {#TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.get} Gets an instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.get(): TExtension | TError +op TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.get(): Extension | Error ``` #### `ExtensionResourceInstanceOperations.update` {#TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.update} @@ -141,7 +141,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.get(): TExtension Updates an existing instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): TExtension | TError +op TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): Extension | Error ``` #### `ExtensionResourceInstanceOperations.delete` {#TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.delete} @@ -149,7 +149,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.update(properties: Deletes an existing instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | TError +op TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | Error ``` ### `ExtensionResourceList` {#TypeSpec.Rest.Resource.ExtensionResourceList} @@ -157,23 +157,23 @@ op TypeSpec.Rest.Resource.ExtensionResourceInstanceOperations.delete(): TypeSpec Extension resource list operation template. ```typespec -interface TypeSpec.Rest.Resource.ExtensionResourceList +interface TypeSpec.Rest.Resource.ExtensionResourceList ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TExtension | The extension resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Extension | The extension resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `ExtensionResourceList.list` {#TypeSpec.Rest.Resource.ExtensionResourceList.list} Lists all instances of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceList.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | TError +op TypeSpec.Rest.Resource.ExtensionResourceList.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ExtensionResourceOperations` {#TypeSpec.Rest.Resource.ExtensionResourceOperations} @@ -181,23 +181,23 @@ op TypeSpec.Rest.Resource.ExtensionResourceList.list(): TypeSpec.Rest.Resource.C Extension resource operation templates for extension resource instances and collections. ```typespec -interface TypeSpec.Rest.Resource.ExtensionResourceOperations +interface TypeSpec.Rest.Resource.ExtensionResourceOperations ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TExtension | The extension resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Extension | The extension resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `ExtensionResourceOperations.get` {#TypeSpec.Rest.Resource.ExtensionResourceOperations.get} Gets an instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceOperations.get(): TExtension | TError +op TypeSpec.Rest.Resource.ExtensionResourceOperations.get(): Extension | Error ``` #### `ExtensionResourceOperations.update` {#TypeSpec.Rest.Resource.ExtensionResourceOperations.update} @@ -205,7 +205,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceOperations.get(): TExtension | TError Updates an existing instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceOperations.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): TExtension | TError +op TypeSpec.Rest.Resource.ExtensionResourceOperations.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): Extension | Error ``` #### `ExtensionResourceOperations.delete` {#TypeSpec.Rest.Resource.ExtensionResourceOperations.delete} @@ -213,7 +213,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceOperations.update(properties: TypeSpe Deletes an existing instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceOperations.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | TError +op TypeSpec.Rest.Resource.ExtensionResourceOperations.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | Error ``` #### `ExtensionResourceOperations.create` {#TypeSpec.Rest.Resource.ExtensionResourceOperations.create} @@ -221,7 +221,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceOperations.delete(): TypeSpec.Rest.Re Creates a new instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceOperations.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): TExtension | TypeSpec.Rest.Resource.ResourceCreatedResponse | TError +op TypeSpec.Rest.Resource.ExtensionResourceOperations.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): Extension | TypeSpec.Rest.Resource.ResourceCreatedResponse | Error ``` #### `ExtensionResourceOperations.list` {#TypeSpec.Rest.Resource.ExtensionResourceOperations.list} @@ -229,7 +229,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceOperations.create(resource: TypeSpec. Lists all instances of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | TError +op TypeSpec.Rest.Resource.ExtensionResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ExtensionResourceRead` {#TypeSpec.Rest.Resource.ExtensionResourceRead} @@ -237,23 +237,23 @@ op TypeSpec.Rest.Resource.ExtensionResourceOperations.list(): TypeSpec.Rest.Reso Extension resource read operation template. ```typespec -interface TypeSpec.Rest.Resource.ExtensionResourceRead +interface TypeSpec.Rest.Resource.ExtensionResourceRead ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TExtension | The extension resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Extension | The extension resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `ExtensionResourceRead.get` {#TypeSpec.Rest.Resource.ExtensionResourceRead.get} Gets an instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceRead.get(): TExtension | TError +op TypeSpec.Rest.Resource.ExtensionResourceRead.get(): Extension | Error ``` ### `ExtensionResourceUpdate` {#TypeSpec.Rest.Resource.ExtensionResourceUpdate} @@ -261,23 +261,23 @@ op TypeSpec.Rest.Resource.ExtensionResourceRead.get(): TExtension | TError Extension resource update operation template. ```typespec -interface TypeSpec.Rest.Resource.ExtensionResourceUpdate +interface TypeSpec.Rest.Resource.ExtensionResourceUpdate ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TExtension | The extension resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Extension | The extension resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `ExtensionResourceUpdate.update` {#TypeSpec.Rest.Resource.ExtensionResourceUpdate.update} Updates an existing instance of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceUpdate.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): TExtension | TError +op TypeSpec.Rest.Resource.ExtensionResourceUpdate.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): Extension | Error ``` ### `ResourceCollectionOperations` {#TypeSpec.Rest.Resource.ResourceCollectionOperations} @@ -285,22 +285,22 @@ op TypeSpec.Rest.Resource.ExtensionResourceUpdate.update(properties: TypeSpec.Re Resource operation templates for resource collections. ```typespec -interface TypeSpec.Rest.Resource.ResourceCollectionOperations +interface TypeSpec.Rest.Resource.ResourceCollectionOperations ``` #### Template Parameters -| Name | Description | -| --------- | ------------------- | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| -------- | ------------------- | +| Resource | The resource model. | +| Error | The error response. | #### `ResourceCollectionOperations.create` {#TypeSpec.Rest.Resource.ResourceCollectionOperations.create} Creates a new instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceCollectionOperations.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): TResource | TypeSpec.Rest.Resource.ResourceCreatedResponse | TError +op TypeSpec.Rest.Resource.ResourceCollectionOperations.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): Resource | TypeSpec.Rest.Resource.ResourceCreatedResponse | Error ``` #### `ResourceCollectionOperations.list` {#TypeSpec.Rest.Resource.ResourceCollectionOperations.list} @@ -308,7 +308,7 @@ op TypeSpec.Rest.Resource.ResourceCollectionOperations.create(resource: TypeSpec Lists all instances of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | TError +op TypeSpec.Rest.Resource.ResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ResourceCreate` {#TypeSpec.Rest.Resource.ResourceCreate} @@ -316,22 +316,22 @@ op TypeSpec.Rest.Resource.ResourceCollectionOperations.list(): TypeSpec.Rest.Res Resource create operation template. ```typespec -interface TypeSpec.Rest.Resource.ResourceCreate +interface TypeSpec.Rest.Resource.ResourceCreate ``` #### Template Parameters -| Name | Description | -| --------- | ----------------------------- | -| TResource | The resource model to create. | -| TError | The error response. | +| Name | Description | +| -------- | ----------------------------- | +| Resource | The resource model to create. | +| Error | The error response. | #### `ResourceCreate.create` {#TypeSpec.Rest.Resource.ResourceCreate.create} Creates a new instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceCreate.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): TResource | TypeSpec.Rest.Resource.ResourceCreatedResponse | TError +op TypeSpec.Rest.Resource.ResourceCreate.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): Resource | TypeSpec.Rest.Resource.ResourceCreatedResponse | Error ``` ### `ResourceCreateOrReplace` {#TypeSpec.Rest.Resource.ResourceCreateOrReplace} @@ -339,22 +339,22 @@ op TypeSpec.Rest.Resource.ResourceCreate.create(resource: TypeSpec.Rest.Resource Resource create or replace operation template. ```typespec -interface TypeSpec.Rest.Resource.ResourceCreateOrReplace +interface TypeSpec.Rest.Resource.ResourceCreateOrReplace ``` #### Template Parameters -| Name | Description | -| --------- | ---------------------------------------- | -| TResource | The resource model to create or replace. | -| TError | The error response. | +| Name | Description | +| -------- | ---------------------------------------- | +| Resource | The resource model to create or replace. | +| Error | The error response. | #### `ResourceCreateOrReplace.createOrReplace` {#TypeSpec.Rest.Resource.ResourceCreateOrReplace.createOrReplace} Creates or replaces a instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceCreateOrReplace.createOrReplace(resource: TypeSpec.Rest.Resource.ResourceCreateModel): TResource | TypeSpec.Rest.Resource.ResourceCreatedResponse | TError +op TypeSpec.Rest.Resource.ResourceCreateOrReplace.createOrReplace(resource: TypeSpec.Rest.Resource.ResourceCreateModel): Resource | TypeSpec.Rest.Resource.ResourceCreatedResponse | Error ``` ### `ResourceCreateOrUpdate` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdate} @@ -362,22 +362,22 @@ op TypeSpec.Rest.Resource.ResourceCreateOrReplace.createOrReplace(resource: Type Resource create or update operation template. ```typespec -interface TypeSpec.Rest.Resource.ResourceCreateOrUpdate +interface TypeSpec.Rest.Resource.ResourceCreateOrUpdate ``` #### Template Parameters -| Name | Description | -| --------- | --------------------------------------- | -| TResource | The resource model to create or update. | -| TError | The error response. | +| Name | Description | +| -------- | --------------------------------------- | +| Resource | The resource model to create or update. | +| Error | The error response. | #### `ResourceCreateOrUpdate.createOrUpdate` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdate.createOrUpdate} Creates or update an instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceCreateOrUpdate.createOrUpdate(resource: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): TResource | TypeSpec.Rest.Resource.ResourceCreatedResponse | TError +op TypeSpec.Rest.Resource.ResourceCreateOrUpdate.createOrUpdate(resource: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): Resource | TypeSpec.Rest.Resource.ResourceCreatedResponse | Error ``` ### `ResourceDelete` {#TypeSpec.Rest.Resource.ResourceDelete} @@ -385,22 +385,22 @@ op TypeSpec.Rest.Resource.ResourceCreateOrUpdate.createOrUpdate(resource: TypeSp Resource delete operation template. ```typespec -interface TypeSpec.Rest.Resource.ResourceDelete +interface TypeSpec.Rest.Resource.ResourceDelete ``` #### Template Parameters -| Name | Description | -| --------- | ----------------------------- | -| TResource | The resource model to delete. | -| TError | The error response. | +| Name | Description | +| -------- | ----------------------------- | +| Resource | The resource model to delete. | +| Error | The error response. | #### `ResourceDelete.delete` {#TypeSpec.Rest.Resource.ResourceDelete.delete} Deletes an existing instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceDelete.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | TError +op TypeSpec.Rest.Resource.ResourceDelete.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | Error ``` ### `ResourceInstanceOperations` {#TypeSpec.Rest.Resource.ResourceInstanceOperations} @@ -408,22 +408,22 @@ op TypeSpec.Rest.Resource.ResourceDelete.delete(): TypeSpec.Rest.Resource.Resour Resource operation templates for resource instances. ```typespec -interface TypeSpec.Rest.Resource.ResourceInstanceOperations +interface TypeSpec.Rest.Resource.ResourceInstanceOperations ``` #### Template Parameters -| Name | Description | -| --------- | ------------------- | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| -------- | ------------------- | +| Resource | The resource model. | +| Error | The error response. | #### `ResourceInstanceOperations.get` {#TypeSpec.Rest.Resource.ResourceInstanceOperations.get} Gets an instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceInstanceOperations.get(): TResource | TError +op TypeSpec.Rest.Resource.ResourceInstanceOperations.get(): Resource | Error ``` #### `ResourceInstanceOperations.update` {#TypeSpec.Rest.Resource.ResourceInstanceOperations.update} @@ -431,7 +431,7 @@ op TypeSpec.Rest.Resource.ResourceInstanceOperations.get(): TResource | TError Updates an existing instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceInstanceOperations.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): TResource | TError +op TypeSpec.Rest.Resource.ResourceInstanceOperations.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): Resource | Error ``` #### `ResourceInstanceOperations.delete` {#TypeSpec.Rest.Resource.ResourceInstanceOperations.delete} @@ -439,7 +439,7 @@ op TypeSpec.Rest.Resource.ResourceInstanceOperations.update(properties: TypeSpec Deletes an existing instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceInstanceOperations.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | TError +op TypeSpec.Rest.Resource.ResourceInstanceOperations.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | Error ``` ### `ResourceList` {#TypeSpec.Rest.Resource.ResourceList} @@ -447,22 +447,22 @@ op TypeSpec.Rest.Resource.ResourceInstanceOperations.delete(): TypeSpec.Rest.Res Resource list operation template. ```typespec -interface TypeSpec.Rest.Resource.ResourceList +interface TypeSpec.Rest.Resource.ResourceList ``` #### Template Parameters -| Name | Description | -| --------- | --------------------------- | -| TResource | The resource model to list. | -| TError | The error response. | +| Name | Description | +| -------- | --------------------------- | +| Resource | The resource model to list. | +| Error | The error response. | #### `ResourceList.list` {#TypeSpec.Rest.Resource.ResourceList.list} Lists all instances of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceList.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | TError +op TypeSpec.Rest.Resource.ResourceList.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ResourceOperations` {#TypeSpec.Rest.Resource.ResourceOperations} @@ -470,22 +470,22 @@ op TypeSpec.Rest.Resource.ResourceList.list(): TypeSpec.Rest.Resource.Collection Resource operation templates for resources. ```typespec -interface TypeSpec.Rest.Resource.ResourceOperations +interface TypeSpec.Rest.Resource.ResourceOperations ``` #### Template Parameters -| Name | Description | -| --------- | ------------------- | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| -------- | ------------------- | +| Resource | The resource model. | +| Error | The error response. | #### `ResourceOperations.get` {#TypeSpec.Rest.Resource.ResourceOperations.get} Gets an instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceOperations.get(): TResource | TError +op TypeSpec.Rest.Resource.ResourceOperations.get(): Resource | Error ``` #### `ResourceOperations.update` {#TypeSpec.Rest.Resource.ResourceOperations.update} @@ -493,7 +493,7 @@ op TypeSpec.Rest.Resource.ResourceOperations.get(): TResource | TError Updates an existing instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceOperations.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): TResource | TError +op TypeSpec.Rest.Resource.ResourceOperations.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): Resource | Error ``` #### `ResourceOperations.delete` {#TypeSpec.Rest.Resource.ResourceOperations.delete} @@ -501,7 +501,7 @@ op TypeSpec.Rest.Resource.ResourceOperations.update(properties: TypeSpec.Rest.Re Deletes an existing instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceOperations.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | TError +op TypeSpec.Rest.Resource.ResourceOperations.delete(): TypeSpec.Rest.Resource.ResourceDeletedResponse | Error ``` #### `ResourceOperations.create` {#TypeSpec.Rest.Resource.ResourceOperations.create} @@ -509,7 +509,7 @@ op TypeSpec.Rest.Resource.ResourceOperations.delete(): TypeSpec.Rest.Resource.Re Creates a new instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceOperations.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): TResource | TypeSpec.Rest.Resource.ResourceCreatedResponse | TError +op TypeSpec.Rest.Resource.ResourceOperations.create(resource: TypeSpec.Rest.Resource.ResourceCreateModel): Resource | TypeSpec.Rest.Resource.ResourceCreatedResponse | Error ``` #### `ResourceOperations.list` {#TypeSpec.Rest.Resource.ResourceOperations.list} @@ -517,30 +517,30 @@ op TypeSpec.Rest.Resource.ResourceOperations.create(resource: TypeSpec.Rest.Reso Lists all instances of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | TError +op TypeSpec.Rest.Resource.ResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ResourceRead` {#TypeSpec.Rest.Resource.ResourceRead} -Represent the resource GET operation. +Represents the resource GET operation. ```typespec -interface TypeSpec.Rest.Resource.ResourceRead +interface TypeSpec.Rest.Resource.ResourceRead ``` #### Template Parameters -| Name | Description | -| --------- | ------------------- | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| -------- | ------------------- | +| Resource | The resource model. | +| Error | The error response. | #### `ResourceRead.get` {#TypeSpec.Rest.Resource.ResourceRead.get} Gets an instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceRead.get(): TResource | TError +op TypeSpec.Rest.Resource.ResourceRead.get(): Resource | Error ``` ### `ResourceUpdate` {#TypeSpec.Rest.Resource.ResourceUpdate} @@ -548,22 +548,22 @@ op TypeSpec.Rest.Resource.ResourceRead.get(): TResource | TError Resource update operation template. ```typespec -interface TypeSpec.Rest.Resource.ResourceUpdate +interface TypeSpec.Rest.Resource.ResourceUpdate ``` #### Template Parameters -| Name | Description | -| --------- | ----------------------------- | -| TResource | The resource model to update. | -| TError | The error response. | +| Name | Description | +| -------- | ----------------------------- | +| Resource | The resource model to update. | +| Error | The error response. | #### `ResourceUpdate.update` {#TypeSpec.Rest.Resource.ResourceUpdate.update} Updates an existing instance of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceUpdate.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): TResource | TError +op TypeSpec.Rest.Resource.ResourceUpdate.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): Resource | Error ``` ### `SingletonResourceOperations` {#TypeSpec.Rest.Resource.SingletonResourceOperations} @@ -571,23 +571,23 @@ op TypeSpec.Rest.Resource.ResourceUpdate.update(properties: TypeSpec.Rest.Resour Singleton resource operation templates for singleton resource instances. ```typespec -interface TypeSpec.Rest.Resource.SingletonResourceOperations +interface TypeSpec.Rest.Resource.SingletonResourceOperations ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TSingleton | The singleton resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Singleton | The singleton resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `SingletonResourceOperations.get` {#TypeSpec.Rest.Resource.SingletonResourceOperations.get} Gets the singleton resource. ```typespec -op TypeSpec.Rest.Resource.SingletonResourceOperations.get(): TSingleton | TError +op TypeSpec.Rest.Resource.SingletonResourceOperations.get(): Singleton | Error ``` #### `SingletonResourceOperations.update` {#TypeSpec.Rest.Resource.SingletonResourceOperations.update} @@ -595,7 +595,7 @@ op TypeSpec.Rest.Resource.SingletonResourceOperations.get(): TSingleton | TError Updates the singleton resource. ```typespec -op TypeSpec.Rest.Resource.SingletonResourceOperations.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): TSingleton | TError +op TypeSpec.Rest.Resource.SingletonResourceOperations.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): Singleton | Error ``` ### `SingletonResourceRead` {#TypeSpec.Rest.Resource.SingletonResourceRead} @@ -603,23 +603,23 @@ op TypeSpec.Rest.Resource.SingletonResourceOperations.update(properties: TypeSpe Singleton resource read operation template. ```typespec -interface TypeSpec.Rest.Resource.SingletonResourceRead +interface TypeSpec.Rest.Resource.SingletonResourceRead ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TSingleton | The singleton resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Singleton | The singleton resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `SingletonResourceRead.get` {#TypeSpec.Rest.Resource.SingletonResourceRead.get} Gets the singleton resource. ```typespec -op TypeSpec.Rest.Resource.SingletonResourceRead.get(): TSingleton | TError +op TypeSpec.Rest.Resource.SingletonResourceRead.get(): Singleton | Error ``` ### `SingletonResourceUpdate` {#TypeSpec.Rest.Resource.SingletonResourceUpdate} @@ -627,21 +627,21 @@ op TypeSpec.Rest.Resource.SingletonResourceRead.get(): TSingleton | TError Singleton resource update operation template. ```typespec -interface TypeSpec.Rest.Resource.SingletonResourceUpdate +interface TypeSpec.Rest.Resource.SingletonResourceUpdate ``` #### Template Parameters -| Name | Description | -| ---------- | ----------------------------- | -| TSingleton | The singleton resource model. | -| TResource | The resource model. | -| TError | The error response. | +| Name | Description | +| --------- | ----------------------------- | +| Singleton | The singleton resource model. | +| Resource | The resource model. | +| Error | The error response. | #### `SingletonResourceUpdate.update` {#TypeSpec.Rest.Resource.SingletonResourceUpdate.update} Updates the singleton resource. ```typespec -op TypeSpec.Rest.Resource.SingletonResourceUpdate.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): TSingleton | TError +op TypeSpec.Rest.Resource.SingletonResourceUpdate.update(properties: TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel): Singleton | Error ``` diff --git a/docs/standard-library/built-in-data-types.md b/docs/standard-library/built-in-data-types.md index a7d0000555..2b52f18677 100644 --- a/docs/standard-library/built-in-data-types.md +++ b/docs/standard-library/built-in-data-types.md @@ -11,13 +11,13 @@ toc_max_heading_level: 3 ```typespec -model Array +model Array ``` #### Template Parameters | Name | Description | |------|-------------| -| T | The type of the array elements | +| Element | The type of the array elements | @@ -26,13 +26,13 @@ model Array Applies a visibility setting to a collection of properties. ```typespec -model DefaultKeyVisibility +model DefaultKeyVisibility ``` #### Template Parameters | Name | Description | |------|-------------| -| T | An object whose properties are spread. | +| Source | An object whose properties are spread. | | Visibility | The visibility to apply to all properties. | @@ -52,13 +52,13 @@ model object Represents a collection of properties with default values omitted. ```typespec -model OmitDefaults +model OmitDefaults ``` #### Template Parameters | Name | Description | |------|-------------| -| T | An object whose spread property defaults are all omitted. | +| Source | An object whose spread property defaults are all omitted. | @@ -67,14 +67,14 @@ model OmitDefaults Represents a collection of omitted properties. ```typespec -model OmitProperties +model OmitProperties ``` #### Template Parameters | Name | Description | |------|-------------| -| T | An object whose properties are spread. | -| TKeys | The property keys to omit. | +| Source | An object whose properties are spread. | +| Keys | The property keys to omit. | @@ -83,13 +83,13 @@ model OmitProperties Represents a collection of optional properties. ```typespec -model OptionalProperties +model OptionalProperties ``` #### Template Parameters | Name | Description | |------|-------------| -| T | An object whose spread properties are all optional. | +| Source | An object whose spread properties are all optional. | @@ -99,13 +99,13 @@ model OptionalProperties ```typespec -model Record +model Record ``` #### Template Parameters | Name | Description | |------|-------------| -| T | The type of the properties | +| Property | The type of the properties | @@ -124,13 +124,13 @@ model ServiceOptions Represents a collection of updateable properties. ```typespec -model UpdateableProperties +model UpdateableProperties ``` #### Template Parameters | Name | Description | |------|-------------| -| T | An object whose spread properties are all updateable. | +| Source | An object whose spread properties are all updateable. | diff --git a/packages/compiler/lib/lib.tsp b/packages/compiler/lib/lib.tsp index a31305f8c9..e656524348 100644 --- a/packages/compiler/lib/lib.tsp +++ b/packages/compiler/lib/lib.tsp @@ -138,18 +138,18 @@ scalar unixTimestamp32 extends utcDateTime; model object {} /** - * @dev Array model type, equivalent to `T[]` - * @template T The type of the array elements + * @dev Array model type, equivalent to `Element[]` + * @template Element The type of the array elements */ -@indexer(integer, T) -model Array {} +@indexer(integer, Element) +model Array {} /** - * @dev Model with string properties where all the properties have type `T` - * @template T The type of the properties + * @dev Model with string properties where all the properties have type `Property` + * @template Property The type of the properties */ -@indexer(string, T) -model Record {} +@indexer(string, Property) +model Record {} /** * Represent a URL string as described by https://url.spec.whatwg.org/ @@ -158,51 +158,56 @@ scalar url extends string; /** * Represents a collection of optional properties. - * @template T An object whose spread properties are all optional. + * + * @template Source An object whose spread properties are all optional. */ @doc("The template for adding optional properties.") @withOptionalProperties -model OptionalProperties { - ...T; +model OptionalProperties { + ...Source; } /** * Represents a collection of updateable properties. - * @template T An object whose spread properties are all updateable. + * + * @template Source An object whose spread properties are all updateable. */ @doc("The template for adding updateable properties.") @withUpdateableProperties -model UpdateableProperties { - ...T; +model UpdateableProperties { + ...Source; } /** * Represents a collection of omitted properties. - * @template T An object whose properties are spread. - * @template TKeys The property keys to omit. + * + * @template Source An object whose properties are spread. + * @template Keys The property keys to omit. */ @doc("The template for omitting properties.") -@withoutOmittedProperties(TKeys) -model OmitProperties { - ...T; +@withoutOmittedProperties(Keys) +model OmitProperties { + ...Source; } /** * Represents a collection of properties with default values omitted. - * @template T An object whose spread property defaults are all omitted. + * + * @template Source An object whose spread property defaults are all omitted. */ @withoutDefaultValues -model OmitDefaults { - ...T; +model OmitDefaults { + ...Source; } /** * Applies a visibility setting to a collection of properties. - * @template T An object whose properties are spread. + * + * @template Source 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 { - ...T; +model DefaultKeyVisibility { + ...Source; } diff --git a/packages/http/lib/auth.tsp b/packages/http/lib/auth.tsp index 11e334bedf..1a98d55024 100644 --- a/packages/http/lib/auth.tsp +++ b/packages/http/lib/auth.tsp @@ -82,19 +82,19 @@ enum ApiKeyLocation { * Cookie: X-API-KEY=abcdef12345 * ``` * - * @template TLocation The location of the API key - * @template TName The name of the API key + * @template Location The location of the API key + * @template Name The name of the API key */ @doc("") -model ApiKeyAuth { +model ApiKeyAuth { @doc("API key authentication") type: AuthType.apiKey; @doc("location of the API key") - in: TLocation; + in: Location; @doc("name of the API key") - name: TName; + name: Name; } /** diff --git a/packages/http/lib/http.tsp b/packages/http/lib/http.tsp index 5ed6a239fb..a7b88cbb68 100644 --- a/packages/http/lib/http.tsp +++ b/packages/http/lib/http.tsp @@ -21,16 +21,16 @@ model Response { /** * Defines a model with a single property of the given type, marked with `@body`. * - * This can be useful in situations where you cannot use a bare T as the body + * This can be useful in situations where you cannot use a bare type as the body * and it is awkward to add a property. * - * @template T The type of the model's `body` property. + * @template TBody The type of the model's `body` property. */ @doc("") -model Body { +model Body { @body @doc("The body type of the operation request or response.") - body: T; + body: TBody; } /** @@ -97,9 +97,10 @@ model ConflictResponse is Response<409>; /** * Produces a new model with the same properties as T, but with `@query`, * `@header`, `@body`, and `@path` decorators removed from all properties. - * @template T The model to spread as the plain data. + * + * @template Data The model to spread as the plain data. */ @plainData -model PlainData { - ...T; +model PlainData { + ...Data; } diff --git a/packages/protobuf/lib/proto.tsp b/packages/protobuf/lib/proto.tsp index cdd173e1b1..33d1ce2288 100644 --- a/packages/protobuf/lib/proto.tsp +++ b/packages/protobuf/lib/proto.tsp @@ -132,11 +132,11 @@ alias integral = int32 | int64 | uint32 | uint64 | boolean; * The key type of a Protobuf `map` must be any integral type or `string`. The value type can be any type other than * another `Map`. * - * @template K the key type (any integral type or string) - * @template V the value type (any type other than another map) + * @template Key the key type (any integral type or string) + * @template Value the value type (any type other than another map) */ @_map -model Map {} +model Map {} /** * Declares that a model is a Protobuf message. diff --git a/packages/rest/lib/resource.tsp b/packages/rest/lib/resource.tsp index e4b932864a..49e7254786 100644 --- a/packages/rest/lib/resource.tsp +++ b/packages/rest/lib/resource.tsp @@ -16,165 +16,182 @@ model ResourceError { } /** - * Dynamically gathers keys of the model type T. - * @template T The target model. + * Dynamically gathers keys of the model type `Resource`. + * + * @template Resource The target resource model. */ -@doc("Dynamically gathers keys of the model type T.") +@doc("Dynamically gathers keys of the model type Resource.") @copyResourceKeyParameters -@friendlyName("{name}Key", T) -model KeysOf {} +@friendlyName("{name}Key", Resource) +model KeysOf {} /** - * Dynamically gathers parent keys of the model type T. - * @template T The target model. + * Dynamically gathers parent keys of the model type `Resource`. + * + * @template Resource The target resource model. */ -@doc("Dynamically gathers parent keys of the model type T.") +@doc("Dynamically gathers parent keys of the model type Resource.") @copyResourceKeyParameters("parent") -@friendlyName("{name}ParentKey", T) -model ParentKeysOf {} +@friendlyName("{name}ParentKey", Resource) +model ParentKeysOf {} /** - * Represents operation parameters for resource TResource. - * @template TResource The resource model. + * Represents operation parameters for the resource of type `Resource`. + * + * @template Resource The resource model. */ -@doc("Represents operation parameters for resource TResource.") -model ResourceParameters { - ...KeysOf; +@doc("Represents operation parameters for resource Resource.") +model ResourceParameters { + ...KeysOf; } /** - * Represents collection operation parameters for resource TResource. - * @template TResource The resource model. + * Represents collection operation parameters for the resource of type `Resource`. + * + * @template Resource The resource model. */ -@doc("Represents collection operation parameters for resource TResource.") -model ResourceCollectionParameters { - ...ParentKeysOf; +@doc("Represents collection operation parameters for resource Resource.") +model ResourceCollectionParameters { + ...ParentKeysOf; } /** - * Represent the resource GET operation. - * @template TResource The resource model. - * @template TError The error response. + * Represents the resource GET operation. + * + * @template Resource The resource model. + * @template Error The error response. */ -@Private.validateHasKey(TResource) -@Private.validateIsError(TError) -interface ResourceRead { +@Private.validateHasKey(Resource) +@Private.validateIsError(Error) +interface ResourceRead { /** * Gets an instance of the resource. - * @template TResource The resource model. + * + * @template Resource The resource model. */ @autoRoute @doc("Gets an instance of the resource.") - @readsResource(TResource) - get(...ResourceParameters): TResource | TError; + @readsResource(Resource) + get(...ResourceParameters): Resource | Error; } /** * Resource create operation completed successfully. - * @template T The resource model that was created. + * + * @template Resource The resource model that was created. */ @doc("Resource create operation completed successfully.") -model ResourceCreatedResponse { +model ResourceCreatedResponse { ...CreatedResponse; - @body body: T; + @body body: Resource; } /** * Resource create or replace operation template. - * @template TResource The resource model to create or replace. - * @template TError The error response. + * + * @template Resource The resource model to create or replace. + * @template Error The error response. */ -interface ResourceCreateOrReplace { +interface ResourceCreateOrReplace { /** * Creates or replaces a instance of the resource. - * @template TResource The resource model to create or replace. - * @template TError The error response. + * + * @template Resource The resource model to create or replace. + * @template Error The error response. */ @autoRoute @doc("Creates or replaces an instance of the resource.") - @createsOrReplacesResource(TResource) + @createsOrReplacesResource(Resource) createOrReplace( - ...ResourceParameters, - @body resource: ResourceCreateModel, - ): TResource | ResourceCreatedResponse | TError; + ...ResourceParameters, + @body resource: ResourceCreateModel, + ): Resource | ResourceCreatedResponse | Error; } /** * Resource create or update operation model. - * @template TResource The resource model to create or update. + * + * @template Resource The resource model to create or update. */ -@friendlyName("{name}Update", TResource) -model ResourceCreateOrUpdateModel - is OptionalProperties>>; +@friendlyName("{name}Update", Resource) +model ResourceCreateOrUpdateModel + is OptionalProperties>>; /** * Resource create or update operation template. - * @template TResource The resource model to create or update. - * @template TError The error response. + * + * @template Resource The resource model to create or update. + * @template Error The error response. */ -interface ResourceCreateOrUpdate { +interface ResourceCreateOrUpdate { /** * Creates or update an instance of the resource. - * @template TResource The resource model to create or update. - * @template TError The error response. + * + * @template Resource The resource model to create or update. + * @template Error The error response. */ @autoRoute @doc("Creates or update an instance of the resource.") - @createsOrUpdatesResource(TResource) + @createsOrUpdatesResource(Resource) createOrUpdate( - ...ResourceParameters, - @body resource: ResourceCreateOrUpdateModel, - ): TResource | ResourceCreatedResponse | TError; + ...ResourceParameters, + @body resource: ResourceCreateOrUpdateModel, + ): Resource | ResourceCreatedResponse | Error; } /** * Resource create operation model. - * @template TResource The resource model to create. + * + * @template Resource The resource model to create. */ -@friendlyName("{name}Create", TResource) +@friendlyName("{name}Create", Resource) @withVisibility("create") -model ResourceCreateModel is DefaultKeyVisibility; +model ResourceCreateModel is DefaultKeyVisibility; /** * Resource create operation template. - * @template TResource The resource model to create. - * @template TError The error response. + * + * @template Resource The resource model to create. + * @template Error The error response. */ -interface ResourceCreate { +interface ResourceCreate { /** * Creates a new instance of the resource. - * @template TResource The resource model to create. - * @template TError The error response. + * + * @template Resource The resource model to create. + * @template Error The error response. */ @autoRoute @doc("Creates a new instance of the resource.") - @createsResource(TResource) + @createsResource(Resource) create( - ...ResourceCollectionParameters, - @body resource: ResourceCreateModel, - ): TResource | ResourceCreatedResponse | TError; + ...ResourceCollectionParameters, + @body resource: ResourceCreateModel, + ): Resource | ResourceCreatedResponse | Error; } /** * Resource update operation template. - * @template TResource The resource model to update. - * @template TError The error response. + * + * @template Resource The resource model to update. + * @template Error The error response. */ -@Private.validateHasKey(TResource) -@Private.validateIsError(TError) -interface ResourceUpdate { +@Private.validateHasKey(Resource) +@Private.validateIsError(Error) +interface ResourceUpdate { /** * Updates an existing instance of the resource. - * @template TResource The resource model to update. - * @template TError The error response. + * + * @template Resource The resource model to update. + * @template Error The error response. */ @autoRoute @doc("Updates an existing instance of the resource.") - @updatesResource(TResource) + @updatesResource(Resource) update( - ...ResourceParameters, - @body properties: ResourceCreateOrUpdateModel, - ): TResource | TError; + ...ResourceParameters, + @body properties: ResourceCreateOrUpdateModel, + ): Resource | Error; } @doc("Resource deleted successfully.") @@ -186,27 +203,31 @@ model ResourceDeletedResponse { /** * Resource delete operation template. - * @template TResource The resource model to delete. - * @template TError The error response. + * + * @template Resource The resource model to delete. + * @template Error The error response. */ -@Private.validateHasKey(TResource) -@Private.validateIsError(TError) -interface ResourceDelete { +@Private.validateHasKey(Resource) +@Private.validateIsError(Error) +interface ResourceDelete { /** * Deletes an existing instance of the resource. - * @template TResource The resource model to delete. - * @template TError The error response. + * + * @template Resource The resource model to delete. + * @template Error The error response. */ @autoRoute @doc("Deletes an existing instance of the resource.") - @deletesResource(TResource) - delete(...ResourceParameters): ResourceDeletedResponse | TError; + @deletesResource(Resource) + delete(...ResourceParameters): ResourceDeletedResponse | Error; } /** * 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. + * + * 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) @@ -221,268 +242,293 @@ model CollectionWithNextLink { /** * Resource list operation template. - * @template TResource The resource model to list. - * @template TError The error response. + * + * @template Resource The resource model to list. + * @template Error The error response. */ -interface ResourceList { +interface ResourceList { /** * Lists all instances of the resource. - * @template TResource The resource model to list. - * @template TError The error response. + * + * @template Resource The resource model to list. + * @template Error The error response. */ @autoRoute @doc("Lists all instances of the resource.") - @listsResource(TResource) - list(...ResourceCollectionParameters): CollectionWithNextLink | TError; + @listsResource(Resource) + list(...ResourceCollectionParameters): CollectionWithNextLink | Error; } /** * Resource operation templates for resource instances. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Resource The resource model. + * @template Error The error response. */ -@Private.validateHasKey(TResource) -@Private.validateIsError(TError) -interface ResourceInstanceOperations - extends ResourceRead, - ResourceUpdate, - ResourceDelete {} +@Private.validateHasKey(Resource) +@Private.validateIsError(Error) +interface ResourceInstanceOperations + extends ResourceRead, + ResourceUpdate, + ResourceDelete {} /** * Resource operation templates for resource collections. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Resource The resource model. + * @template Error The error response. */ -@Private.validateHasKey(TResource) -@Private.validateIsError(TError) -interface ResourceCollectionOperations - extends ResourceCreate, - ResourceList {} +@Private.validateHasKey(Resource) +@Private.validateIsError(Error) +interface ResourceCollectionOperations + extends ResourceCreate, + ResourceList {} /** * Resource operation templates for resources. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Resource The resource model. + * @template Error The error response. */ -@Private.validateHasKey(TResource) -@Private.validateIsError(TError) -interface ResourceOperations - extends ResourceInstanceOperations, - ResourceCollectionOperations {} +@Private.validateHasKey(Resource) +@Private.validateIsError(Error) +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. + * + * @template Singleton The singleton resource model. + * @template Resource The resource model. + * @template Error The error response. */ -@Private.validateHasKey(TResource) -@Private.validateIsError(TError) -interface SingletonResourceRead { +@Private.validateHasKey(Resource) +@Private.validateIsError(Error) +interface SingletonResourceRead { /** * Gets the singleton resource. - * @template TSingleton The singleton resource model. - * @template TResource The resource model. + * + * @template Singleton The singleton resource model. + * @template Resource The resource model. */ @autoRoute @doc("Gets the singleton resource.") - @segmentOf(TSingleton) - @readsResource(TSingleton) - get(...ResourceParameters): TSingleton | TError; + @segmentOf(Singleton) + @readsResource(Singleton) + get(...ResourceParameters): Singleton | Error; } /** * Singleton resource update operation template. - * @template TSingleton The singleton resource model. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Singleton The singleton resource model. + * @template Resource The resource model. + * @template Error The error response. */ -@Private.validateHasKey(TResource) -@Private.validateIsError(TError) -interface SingletonResourceUpdate { +@Private.validateHasKey(Resource) +@Private.validateIsError(Error) +interface SingletonResourceUpdate { /** * Updates the singleton resource. - * @template TSingleton The singleton resource model. - * @template TResource The resource model. + * + * @template Singleton The singleton resource model. + * @template Resource The resource model. */ @autoRoute @doc("Updates the singleton resource.") - @segmentOf(TSingleton) - @updatesResource(TSingleton) + @segmentOf(Singleton) + @updatesResource(Singleton) update( - ...ResourceParameters, + ...ResourceParameters, @body - properties: ResourceCreateOrUpdateModel, - ): TSingleton | TError; + properties: ResourceCreateOrUpdateModel, + ): Singleton | Error; } /** * Singleton resource operation templates for singleton resource instances. - * @template TSingleton The singleton resource model. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Singleton The singleton resource model. + * @template Resource The resource model. + * @template Error The error response. */ -interface SingletonResourceOperations - extends SingletonResourceRead, - SingletonResourceUpdate {} +interface SingletonResourceOperations + extends SingletonResourceRead, + SingletonResourceUpdate {} /** * Extension resource read operation template. - * @template TExtension The extension resource model. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Extension The extension resource model. + * @template Resource The resource model. + * @template Error The error response. */ -@Private.validateHasKey(TResource) -@Private.validateIsError(TError) -interface ExtensionResourceRead { +@Private.validateHasKey(Resource) +@Private.validateIsError(Error) +interface ExtensionResourceRead { /** * Gets an instance of the extension resource. - * @template TExtension The extension resource model. - * @template TResource The resource model. + * + * @template Extension The extension resource model. + * @template Resource The resource model. */ @autoRoute @doc("Gets an instance of the extension resource.") - @readsResource(TExtension) - get(...ResourceParameters, ...ResourceParameters): TExtension | TError; + @readsResource(Extension) + get(...ResourceParameters, ...ResourceParameters): Extension | Error; } /** * Extension resource create or update operation template. - * @template TExtension The extension resource model. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Extension The extension resource model. + * @template Resource The resource model. + * @template Error The error response. */ -interface ExtensionResourceCreateOrUpdate { +interface ExtensionResourceCreateOrUpdate { /** * Creates or update an instance of the extension resource. - * @template TExtension The extension resource model. - * @template TResource The resource model. + * + * @template Extension The extension resource model. + * @template Resource The resource model. */ @autoRoute @doc("Creates or update an instance of the extension resource.") - @createsOrUpdatesResource(TExtension) + @createsOrUpdatesResource(Extension) createOrUpdate( - ...ResourceParameters, - ...ResourceParameters, - @body resource: ResourceCreateOrUpdateModel, - ): TExtension | ResourceCreatedResponse | TError; + ...ResourceParameters, + ...ResourceParameters, + @body resource: ResourceCreateOrUpdateModel, + ): Extension | ResourceCreatedResponse | Error; } /** * Extension resource create operation template. - * @template TExtension The extension resource model. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Extension The extension resource model. + * @template Resource The resource model. + * @template Error The error response. */ -interface ExtensionResourceCreate { +interface ExtensionResourceCreate { /** * Creates a new instance of the extension resource. - * @template TExtension The extension resource model. - * @template TResource The resource model. + * + * @template Extension The extension resource model. + * @template Resource The resource model. */ @autoRoute @doc("Creates a new instance of the extension resource.") - @createsResource(TExtension) + @createsResource(Extension) create( - ...ResourceParameters, - @body resource: ResourceCreateModel, - ): TExtension | ResourceCreatedResponse | TError; + ...ResourceParameters, + @body resource: ResourceCreateModel, + ): Extension | ResourceCreatedResponse | Error; } /** * Extension resource update operation template. - * @template TExtension The extension resource model. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Extension The extension resource model. + * @template Resource The resource model. + * @template Error The error response. */ -interface ExtensionResourceUpdate { +interface ExtensionResourceUpdate { /** * Updates an existing instance of the extension resource. - * @template TExtension The extension resource model. - * @template TResource The resource model. + * + * @template Extension The extension resource model. + * @template Resource The resource model. */ @autoRoute @doc("Updates an existing instance of the extension resource.") - @updatesResource(TExtension) + @updatesResource(Extension) update( - ...ResourceParameters, - ...ResourceParameters, + ...ResourceParameters, + ...ResourceParameters, @body - properties: ResourceCreateOrUpdateModel, - ): TExtension | TError; + properties: ResourceCreateOrUpdateModel, + ): Extension | Error; } /** * Extension resource delete operation template. - * @template TExtension The extension resource model. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Extension The extension resource model. + * @template Resource The resource model. + * @template Error The error response. */ -interface ExtensionResourceDelete { +interface ExtensionResourceDelete { /** * Deletes an existing instance of the extension resource. - * @template TExtension The extension resource model. - * @template TResource The resource model. + * + * @template Extension The extension resource model. + * @template Resource The resource model. */ @autoRoute @doc("Deletes an existing instance of the extension resource.") - @deletesResource(TExtension) + @deletesResource(Extension) delete( - ...ResourceParameters, - ...ResourceParameters, - ): ResourceDeletedResponse | TError; + ...ResourceParameters, + ...ResourceParameters, + ): ResourceDeletedResponse | Error; } /** * Extension resource list operation template. - * @template TExtension The extension resource model. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Extension The extension resource model. + * @template Resource The resource model. + * @template Error The error response. */ -interface ExtensionResourceList { +interface ExtensionResourceList { /** * Lists all instances of the extension resource. - * @template TExtension The extension resource model. - * @template TResource The resource model. + * + * @template Extension The extension resource model. + * @template Resource The resource model. */ @autoRoute @doc("Lists all instances of the extension resource.") - @listsResource(TExtension) + @listsResource(Extension) list( - ...ResourceParameters, - ...ResourceCollectionParameters, - ): CollectionWithNextLink | TError; + ...ResourceParameters, + ...ResourceCollectionParameters, + ): CollectionWithNextLink | Error; } /** * Extension resource operation templates for extension resource instances. - * @template TExtension The extension resource model. - * @template TResource The resource model. - * @template TError The error response. + * + * @template Extension The extension resource model. + * @template Resource The resource model. + * @template Error The error response. */ -interface ExtensionResourceInstanceOperations - extends ExtensionResourceRead, - ExtensionResourceUpdate, - ExtensionResourceDelete {} +interface ExtensionResourceInstanceOperations + extends ExtensionResourceRead, + 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. + * + * @template Extension The extension resource model. + * @template Resource The resource model. + * @template Error The error response. */ -interface ExtensionResourceCollectionOperations - extends ExtensionResourceCreate, - ExtensionResourceList {} +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. + * + * @template Extension The extension resource model. + * @template Resource The resource model. + * @template Error The error response. */ -interface ExtensionResourceOperations - extends ExtensionResourceInstanceOperations, - ExtensionResourceCollectionOperations {} +interface ExtensionResourceOperations + extends ExtensionResourceInstanceOperations, + ExtensionResourceCollectionOperations {} diff --git a/packages/samples/specs/petstore/petstore.tsp b/packages/samples/specs/petstore/petstore.tsp index fc23c6bb6f..c917efd85b 100644 --- a/packages/samples/specs/petstore/petstore.tsp +++ b/packages/samples/specs/petstore/petstore.tsp @@ -35,14 +35,14 @@ model Error { } @doc("Not modified") -model NotModified { +model NotModified { @statusCode _: 304; - @body body: T; + @body body: Body; } @friendlyName("{name}ListResults", T) -model ResponsePage { - items: T[]; +model ResponsePage { + items: Item[]; nextLink?: string; } diff --git a/packages/samples/specs/signatures/signatures.tsp b/packages/samples/specs/signatures/signatures.tsp index a5cdadc094..ca8bcf0d2d 100644 --- a/packages/samples/specs/signatures/signatures.tsp +++ b/packages/samples/specs/signatures/signatures.tsp @@ -17,14 +17,14 @@ model AccountProfile { } @get -@doc("Reads an instance of the {name} resource.", TResource) -op ResourceReadBase(@path name: string): TResource | TError; -op ResourceRead is ResourceReadBase; +@doc("Reads an instance of the {name} resource.", Resource) +op ResourceReadBase(@path name: string): Resource | Error; +op ResourceRead is ResourceReadBase; @post -@doc("Reads an instance of the {name} resource.", TResource) -op ResourceCreateBase(@body resource: TResource): TResource | TError; -op ResourceCreate is ResourceCreateBase; +@doc("Reads an instance of the {name} resource.", Resource) +op ResourceCreateBase(@body resource: Resource): Resource | Error; +op ResourceCreate is ResourceCreateBase; @route("codeSignAccounts") interface CodeSignAccounts { @@ -32,9 +32,9 @@ interface CodeSignAccounts { create is ResourceCreate; } -interface ResourceOperations { - get is ResourceRead; - create is ResourceCreate; +interface ResourceOperations { + get is ResourceRead; + create is ResourceCreate; } @route("accountProfiles") diff --git a/packages/samples/specs/visibility/visibility.tsp b/packages/samples/specs/visibility/visibility.tsp index dce916cbd6..332f29d132 100644 --- a/packages/samples/specs/visibility/visibility.tsp +++ b/packages/samples/specs/visibility/visibility.tsp @@ -30,13 +30,13 @@ model PersonRelative { } @withVisibility("read") -model Readable { - ...T; +model Readable { + ...Data; } @withVisibility("create") -model Writable { - ...T; +model Writable { + ...Data; } model ReadablePerson { @@ -55,8 +55,8 @@ model WriteableOptionalPerson { ...OptionalProperties; } -model ListResult { - items: T[]; +model ListResult { + items: Item[]; } @route("/hello") From 5112c707b3d8a140ae008f1083466b58d7efcb7f Mon Sep 17 00:00:00 2001 From: Will Temple Date: Thu, 30 Nov 2023 12:49:24 -0500 Subject: [PATCH 02/11] Fixed some stragglers that weren't included in the first commit. --- docs/libraries/http/reference/data-types.md | 9 +++++---- docs/libraries/json-schema/reference/data-types.md | 4 ++-- docs/libraries/json-schema/reference/decorators.md | 10 +++++----- docs/libraries/rest/reference/data-types.md | 4 ++-- docs/libraries/rest/reference/interfaces.md | 12 ++++++------ docs/standard-library/built-in-decorators.md | 6 +++--- packages/compiler/lib/decorators.tsp | 6 +++--- packages/http/lib/auth.tsp | 8 +++++--- packages/json-schema/README.md | 10 +++++----- packages/json-schema/lib/main.tsp | 12 ++++++------ packages/rest/lib/resource.tsp | 12 ++++++------ packages/rest/lib/rest.tsp | 8 ++++---- 12 files changed, 52 insertions(+), 49 deletions(-) diff --git a/docs/libraries/http/reference/data-types.md b/docs/libraries/http/reference/data-types.md index d78317cca8..92a7cb45d1 100644 --- a/docs/libraries/http/reference/data-types.md +++ b/docs/libraries/http/reference/data-types.md @@ -201,19 +201,20 @@ model TypeSpec.Http.NotModifiedResponse ### `OAuth2Auth` {#TypeSpec.Http.OAuth2Auth} OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server. + 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. ```typespec -model TypeSpec.Http.OAuth2Auth +model TypeSpec.Http.OAuth2Auth ``` #### Template Parameters -| Name | Description | -| ------ | ---------------------------------- | -| TFlows | The list of supported OAuth2 flows | +| Name | Description | +| ----- | ---------------------------------- | +| Flows | The list of supported OAuth2 flows | ### `OkResponse` {#TypeSpec.Http.OkResponse} diff --git a/docs/libraries/json-schema/reference/data-types.md b/docs/libraries/json-schema/reference/data-types.md index e07738cf02..385b1d1a99 100644 --- a/docs/libraries/json-schema/reference/data-types.md +++ b/docs/libraries/json-schema/reference/data-types.md @@ -14,14 +14,14 @@ Specify that the provided template argument should be emitted as raw JSON or YAM as opposed to a schema. Use in combination with the ```typespec -model TypeSpec.JsonSchema.Json +model TypeSpec.JsonSchema.Json ``` #### Template Parameters | Name | Description | | ---- | ------------------------------- | -| T | the type to convert to raw JSON | +| Data | the type to convert to raw JSON | ### `Format` {#TypeSpec.JsonSchema.Format} diff --git a/docs/libraries/json-schema/reference/decorators.md b/docs/libraries/json-schema/reference/decorators.md index d039d2027f..cf75aea96c 100644 --- a/docs/libraries/json-schema/reference/decorators.md +++ b/docs/libraries/json-schema/reference/decorators.md @@ -104,7 +104,7 @@ media type and encoding. Specify a custom property to add to the emitted schema. Useful for adding custom keywords and other vendor-specific extensions. The value will be converted to a schema unless the parameter -is wrapped in the `Json` template. For example, `@extension("x-schema", { x: "value" })` will +is wrapped in the `Json` template. For example, `@extension("x-schema", { x: "value" })` will emit a JSON schema value for `x-schema`, whereas `@extension("x-schema", Json<{x: "value"}>)` will emit the raw JSON code `{x: "value"}`. @@ -118,10 +118,10 @@ emit the raw JSON code `{x: "value"}`. #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ------------------------------------------------------------------------------------ | -| key | `valueof scalar string` | the name of the keyword of vendor extension, e.g. `x-custom`. | -| value | `(intrinsic) unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | +| Name | Type | Description | +| ----- | ----------------------- | --------------------------------------------------------------------------------------- | +| key | `valueof scalar string` | the name of the keyword of vendor extension, e.g. `x-custom`. | +| value | `(intrinsic) unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | ### `@id` {#@TypeSpec.JsonSchema.id} diff --git a/docs/libraries/rest/reference/data-types.md b/docs/libraries/rest/reference/data-types.md index ef10617492..2cfd8a5290 100644 --- a/docs/libraries/rest/reference/data-types.md +++ b/docs/libraries/rest/reference/data-types.md @@ -26,14 +26,14 @@ This only provides the model structure and not actual pagination support. See https://github.com/microsoft/typespec/issues/705 for general paging support. ```typespec -model TypeSpec.Rest.Resource.CollectionWithNextLink +model TypeSpec.Rest.Resource.CollectionWithNextLink ``` #### Template Parameters | Name | Description | | ---- | ------------------------------------ | -| T | The resource type of the collection. | +| Item | The resource type of the collection. | ### `KeysOf` {#TypeSpec.Rest.Resource.KeysOf} diff --git a/docs/libraries/rest/reference/interfaces.md b/docs/libraries/rest/reference/interfaces.md index 09077a31b1..83239f4f14 100644 --- a/docs/libraries/rest/reference/interfaces.md +++ b/docs/libraries/rest/reference/interfaces.md @@ -37,7 +37,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.create(resource: Lists all instances of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error +op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ExtensionResourceCreate` {#TypeSpec.Rest.Resource.ExtensionResourceCreate} @@ -173,7 +173,7 @@ interface TypeSpec.Rest.Resource.ExtensionResourceList | Error +op TypeSpec.Rest.Resource.ExtensionResourceList.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ExtensionResourceOperations` {#TypeSpec.Rest.Resource.ExtensionResourceOperations} @@ -229,7 +229,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceOperations.create(resource: TypeSpec. Lists all instances of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error +op TypeSpec.Rest.Resource.ExtensionResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ExtensionResourceRead` {#TypeSpec.Rest.Resource.ExtensionResourceRead} @@ -308,7 +308,7 @@ op TypeSpec.Rest.Resource.ResourceCollectionOperations.create(resource: TypeSpec Lists all instances of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error +op TypeSpec.Rest.Resource.ResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ResourceCreate` {#TypeSpec.Rest.Resource.ResourceCreate} @@ -462,7 +462,7 @@ interface TypeSpec.Rest.Resource.ResourceList Lists all instances of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceList.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error +op TypeSpec.Rest.Resource.ResourceList.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ResourceOperations` {#TypeSpec.Rest.Resource.ResourceOperations} @@ -517,7 +517,7 @@ op TypeSpec.Rest.Resource.ResourceOperations.create(resource: TypeSpec.Rest.Reso Lists all instances of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error +op TypeSpec.Rest.Resource.ResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ResourceRead` {#TypeSpec.Rest.Resource.ResourceRead} diff --git a/docs/standard-library/built-in-decorators.md b/docs/standard-library/built-in-decorators.md index d97bfa5d00..dadccddf95 100644 --- a/docs/standard-library/built-in-decorators.md +++ b/docs/standard-library/built-in-decorators.md @@ -30,7 +30,7 @@ Use the `#deprecated` directive instead: ```typespec #deprecated "Use ActionV2" -op Action(): T; +op Action(): Result; ``` @@ -233,8 +233,8 @@ Specifies how a templated type should name their instances. ```typespec @friendlyName("{name}List", T) -model List { -value: T[]; +model List { +value: Item[]; nextLink: string; } ``` diff --git a/packages/compiler/lib/decorators.tsp b/packages/compiler/lib/decorators.tsp index 4988ccafc1..47f7eb3d83 100644 --- a/packages/compiler/lib/decorators.tsp +++ b/packages/compiler/lib/decorators.tsp @@ -69,7 +69,7 @@ extern dec errorsDoc(target: Operation, doc: valueof string); * * ```typespec * #deprecated "Use ActionV2" - * op Action(): T; + * op Action(): Result; * ``` */ #deprecated "@deprecated decorator is deprecated. Use the `#deprecated` directive instead." @@ -288,8 +288,8 @@ extern dec tag(target: Namespace | Interface | Operation, tag: valueof string); * @example * ```typespec * @friendlyName("{name}List", T) - * model List { - * value: T[]; + * model List { + * value: Item[]; * nextLink: string; * } * ``` diff --git a/packages/http/lib/auth.tsp b/packages/http/lib/auth.tsp index 1a98d55024..3ee66aebee 100644 --- a/packages/http/lib/auth.tsp +++ b/packages/http/lib/auth.tsp @@ -99,18 +99,20 @@ model ApiKeyAuth { /** * OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server. + * * 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 + * + * @template Flows The list of supported OAuth2 flows */ @doc("") -model OAuth2Auth { +model OAuth2Auth { @doc("OAuth2 authentication") type: AuthType.oauth2; @doc("Supported OAuth2 flows") - flows: TFlows; + flows: Flows; } @doc("Describes the OAuth2 flow type") diff --git a/packages/json-schema/README.md b/packages/json-schema/README.md index 435139e15b..562a597035 100644 --- a/packages/json-schema/README.md +++ b/packages/json-schema/README.md @@ -194,7 +194,7 @@ media type and encoding. Specify a custom property to add to the emitted schema. Useful for adding custom keywords and other vendor-specific extensions. The value will be converted to a schema unless the parameter -is wrapped in the `Json` template. For example, `@extension("x-schema", { x: "value" })` will +is wrapped in the `Json` template. For example, `@extension("x-schema", { x: "value" })` will emit a JSON schema value for `x-schema`, whereas `@extension("x-schema", Json<{x: "value"}>)` will emit the raw JSON code `{x: "value"}`. @@ -208,10 +208,10 @@ emit the raw JSON code `{x: "value"}`. ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ------------------------------------------------------------------------------------ | -| key | `valueof scalar string` | the name of the keyword of vendor extension, e.g. `x-custom`. | -| value | `(intrinsic) unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | +| Name | Type | Description | +| ----- | ----------------------- | --------------------------------------------------------------------------------------- | +| key | `valueof scalar string` | the name of the keyword of vendor extension, e.g. `x-custom`. | +| value | `(intrinsic) unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | #### `@id` diff --git a/packages/json-schema/lib/main.tsp b/packages/json-schema/lib/main.tsp index 4da3009ea4..fae17c91d9 100644 --- a/packages/json-schema/lib/main.tsp +++ b/packages/json-schema/lib/main.tsp @@ -112,12 +112,12 @@ extern dec contentSchema(target: string | Reflection.ModelProperty, value: unkno /** * Specify a custom property to add to the emitted schema. Useful for adding custom keywords * and other vendor-specific extensions. The value will be converted to a schema unless the parameter - * is wrapped in the `Json` template. For example, `@extension("x-schema", { x: "value" })` will + * is wrapped in the `Json` template. For example, `@extension("x-schema", { x: "value" })` will * emit a JSON schema value for `x-schema`, whereas `@extension("x-schema", Json<{x: "value"}>)` will * emit the raw JSON code `{x: "value"}`. * * @param key the name of the keyword of vendor extension, e.g. `x-custom`. - * @param value the value of the keyword. Will be converted to a schema unless wrapped in `Json`. + * @param value the value of the keyword. Will be converted to a schema unless wrapped in `Json`. */ extern dec extension(target: unknown, key: valueof string, value: unknown); @@ -152,11 +152,11 @@ enum Format { * whereas `@extension("x-schema", Json<{x: "value"}>)` will emit the raw JSON code * `{x: "value"}`. * - * @template T the type to convert to raw JSON + * @template Data the type to convert to raw JSON */ -@Private.validatesRawJson(T) -model Json { - value: T; +@Private.validatesRawJson(Data) +model Json { + value: Data; } namespace Private { diff --git a/packages/rest/lib/resource.tsp b/packages/rest/lib/resource.tsp index 49e7254786..33c8360802 100644 --- a/packages/rest/lib/resource.tsp +++ b/packages/rest/lib/resource.tsp @@ -228,16 +228,16 @@ interface ResourceDelete { * 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. + * @template Item The resource type of the collection. */ -@doc("Paged response of {name} items", T) -@friendlyName("{name}CollectionWithNextLink", T) -model CollectionWithNextLink { +@doc("Paged response of {name} items", Item) +@friendlyName("{name}CollectionWithNextLink", Item) +model CollectionWithNextLink { @doc("The items on this page") - value: T[]; + value: Item[]; @doc("The link to the next page of items") - nextLink?: ResourceLocation; + nextLink?: ResourceLocation; } /** diff --git a/packages/rest/lib/rest.tsp b/packages/rest/lib/rest.tsp index 7781e2628f..dae696d37a 100644 --- a/packages/rest/lib/rest.tsp +++ b/packages/rest/lib/rest.tsp @@ -6,8 +6,8 @@ namespace TypeSpec.Rest; /** * A URL that points to a resource. - * @template TResource The type of resource that the URL points to. + * @template Resource 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; +@doc("The location of an instance of {name}", Resource) +@Private.resourceLocation(Resource) +scalar ResourceLocation extends url; From d61929321632af5acf6bc7a9209b3df07e86dd4d Mon Sep 17 00:00:00 2001 From: Will Temple Date: Mon, 4 Dec 2023 16:45:26 -0500 Subject: [PATCH 03/11] Rush change --- .../rename-template-params_2023-12-04-21-45.json | 10 ++++++++++ .../http/rename-template-params_2023-12-04-21-45.json | 10 ++++++++++ .../rename-template-params_2023-12-04-21-45.json | 10 ++++++++++ .../rename-template-params_2023-12-04-21-45.json | 10 ++++++++++ .../rest/rename-template-params_2023-12-04-21-45.json | 10 ++++++++++ 5 files changed, 50 insertions(+) create mode 100644 common/changes/@typespec/compiler/rename-template-params_2023-12-04-21-45.json create mode 100644 common/changes/@typespec/http/rename-template-params_2023-12-04-21-45.json create mode 100644 common/changes/@typespec/json-schema/rename-template-params_2023-12-04-21-45.json create mode 100644 common/changes/@typespec/protobuf/rename-template-params_2023-12-04-21-45.json create mode 100644 common/changes/@typespec/rest/rename-template-params_2023-12-04-21-45.json diff --git a/common/changes/@typespec/compiler/rename-template-params_2023-12-04-21-45.json b/common/changes/@typespec/compiler/rename-template-params_2023-12-04-21-45.json new file mode 100644 index 0000000000..539e5b5d9d --- /dev/null +++ b/common/changes/@typespec/compiler/rename-template-params_2023-12-04-21-45.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@typespec/compiler", + "comment": "Rename template parameters in preparation for named template argument instantiation.", + "type": "none" + } + ], + "packageName": "@typespec/compiler" +} \ No newline at end of file diff --git a/common/changes/@typespec/http/rename-template-params_2023-12-04-21-45.json b/common/changes/@typespec/http/rename-template-params_2023-12-04-21-45.json new file mode 100644 index 0000000000..031f609fa3 --- /dev/null +++ b/common/changes/@typespec/http/rename-template-params_2023-12-04-21-45.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@typespec/http", + "comment": "Rename template parameters in preparation for named template argument instantiation.", + "type": "none" + } + ], + "packageName": "@typespec/http" +} \ No newline at end of file diff --git a/common/changes/@typespec/json-schema/rename-template-params_2023-12-04-21-45.json b/common/changes/@typespec/json-schema/rename-template-params_2023-12-04-21-45.json new file mode 100644 index 0000000000..37570bd6af --- /dev/null +++ b/common/changes/@typespec/json-schema/rename-template-params_2023-12-04-21-45.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@typespec/json-schema", + "comment": "Rename template parameters in preparation for named template argument instantiation.", + "type": "none" + } + ], + "packageName": "@typespec/json-schema" +} \ No newline at end of file diff --git a/common/changes/@typespec/protobuf/rename-template-params_2023-12-04-21-45.json b/common/changes/@typespec/protobuf/rename-template-params_2023-12-04-21-45.json new file mode 100644 index 0000000000..0df789948f --- /dev/null +++ b/common/changes/@typespec/protobuf/rename-template-params_2023-12-04-21-45.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@typespec/protobuf", + "comment": "Rename template parameters in preparation for named template argument instantiation.", + "type": "none" + } + ], + "packageName": "@typespec/protobuf" +} \ No newline at end of file diff --git a/common/changes/@typespec/rest/rename-template-params_2023-12-04-21-45.json b/common/changes/@typespec/rest/rename-template-params_2023-12-04-21-45.json new file mode 100644 index 0000000000..a73b4d6e62 --- /dev/null +++ b/common/changes/@typespec/rest/rename-template-params_2023-12-04-21-45.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@typespec/rest", + "comment": "Rename template parameters in preparation for named template argument instantiation.", + "type": "none" + } + ], + "packageName": "@typespec/rest" +} \ No newline at end of file From 047630604cb78b222858f625a0a11692a5d10882 Mon Sep 17 00:00:00 2001 From: Will Temple Date: Mon, 4 Dec 2023 17:26:42 -0500 Subject: [PATCH 04/11] Update test expectations in compiler --- packages/compiler/test/server/completion.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/compiler/test/server/completion.test.ts b/packages/compiler/test/server/completion.test.ts index 91e4365fb2..0e10df39ba 100644 --- a/packages/compiler/test/server/completion.test.ts +++ b/packages/compiler/test/server/completion.test.ts @@ -37,7 +37,7 @@ describe("compiler: server: completion", () => { label: "Record", insertText: "Record", kind: CompletionItemKind.Class, - documentation: { kind: MarkupKind.Markdown, value: "```typespec\nmodel Record\n```" }, + documentation: { kind: MarkupKind.Markdown, value: "```typespec\nmodel Record\n```" }, }, ]); }); From 8c453f29d810ee83f74233ef25693fa3e61cc825 Mon Sep 17 00:00:00 2001 From: Will Temple Date: Mon, 4 Dec 2023 17:43:29 -0500 Subject: [PATCH 05/11] Fixed a sample --- packages/samples/specs/petstore/petstore.tsp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/samples/specs/petstore/petstore.tsp b/packages/samples/specs/petstore/petstore.tsp index c917efd85b..0ece491f85 100644 --- a/packages/samples/specs/petstore/petstore.tsp +++ b/packages/samples/specs/petstore/petstore.tsp @@ -40,7 +40,7 @@ model NotModified { @body body: Body; } -@friendlyName("{name}ListResults", T) +@friendlyName("{name}ListResults", Item) model ResponsePage { items: Item[]; nextLink?: string; From a022ca95155e852e25619cda469c253707ec50f7 Mon Sep 17 00:00:00 2001 From: Will Temple Date: Wed, 13 Dec 2023 12:39:47 -0500 Subject: [PATCH 06/11] Addressed some feedback --- packages/http/lib/http.tsp | 6 +++--- packages/rest/lib/resource.tsp | 12 ++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/packages/http/lib/http.tsp b/packages/http/lib/http.tsp index a7b88cbb68..1b1d8d7557 100644 --- a/packages/http/lib/http.tsp +++ b/packages/http/lib/http.tsp @@ -24,13 +24,13 @@ model Response { * This can be useful in situations where you cannot use a bare type as the body * and it is awkward to add a property. * - * @template TBody The type of the model's `body` property. + * @template Type The type of the model's `body` property. */ @doc("") -model Body { +model Body { @body @doc("The body type of the operation request or response.") - body: TBody; + body: Type; } /** diff --git a/packages/rest/lib/resource.tsp b/packages/rest/lib/resource.tsp index 33c8360802..7f3da7cf19 100644 --- a/packages/rest/lib/resource.tsp +++ b/packages/rest/lib/resource.tsp @@ -228,16 +228,16 @@ interface ResourceDelete { * This only provides the model structure and not actual pagination support. See * https://github.com/microsoft/typespec/issues/705 for general paging support. * - * @template Item The resource type of the collection. + * @template Resource The resource type of the collection. */ -@doc("Paged response of {name} items", Item) -@friendlyName("{name}CollectionWithNextLink", Item) -model CollectionWithNextLink { +@doc("Paged response of {name} items", Resource) +@friendlyName("{name}CollectionWithNextLink", Resource) +model CollectionWithNextLink { @doc("The items on this page") - value: Item[]; + value: Resource[]; @doc("The link to the next page of items") - nextLink?: ResourceLocation; + nextLink?: ResourceLocation; } /** From 22fd43e8bb809fb3665ddf7a64c36bd5ee493bab Mon Sep 17 00:00:00 2001 From: Will Temple Date: Wed, 13 Dec 2023 12:45:38 -0500 Subject: [PATCH 07/11] Updated docs --- docs/libraries/http/reference/data-types.md | 8 ++++---- docs/libraries/rest/reference/data-types.md | 8 ++++---- docs/libraries/rest/reference/interfaces.md | 12 ++++++------ 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/libraries/http/reference/data-types.md b/docs/libraries/http/reference/data-types.md index 92a7cb45d1..488d487263 100644 --- a/docs/libraries/http/reference/data-types.md +++ b/docs/libraries/http/reference/data-types.md @@ -101,14 +101,14 @@ This can be useful in situations where you cannot use a bare type as the body and it is awkward to add a property. ```typespec -model TypeSpec.Http.Body +model TypeSpec.Http.Body ``` #### Template Parameters -| Name | Description | -| ----- | ---------------------------------------- | -| TBody | The type of the model's `body` property. | +| Name | Description | +| ---- | ---------------------------------------- | +| Type | The type of the model's `body` property. | ### `ClientCredentialsFlow` {#TypeSpec.Http.ClientCredentialsFlow} diff --git a/docs/libraries/rest/reference/data-types.md b/docs/libraries/rest/reference/data-types.md index 2cfd8a5290..b179018191 100644 --- a/docs/libraries/rest/reference/data-types.md +++ b/docs/libraries/rest/reference/data-types.md @@ -26,14 +26,14 @@ This only provides the model structure and not actual pagination support. See https://github.com/microsoft/typespec/issues/705 for general paging support. ```typespec -model TypeSpec.Rest.Resource.CollectionWithNextLink +model TypeSpec.Rest.Resource.CollectionWithNextLink ``` #### Template Parameters -| Name | Description | -| ---- | ------------------------------------ | -| Item | The resource type of the collection. | +| Name | Description | +| -------- | ------------------------------------ | +| Resource | The resource type of the collection. | ### `KeysOf` {#TypeSpec.Rest.Resource.KeysOf} diff --git a/docs/libraries/rest/reference/interfaces.md b/docs/libraries/rest/reference/interfaces.md index 83239f4f14..14876462be 100644 --- a/docs/libraries/rest/reference/interfaces.md +++ b/docs/libraries/rest/reference/interfaces.md @@ -37,7 +37,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.create(resource: Lists all instances of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error +op TypeSpec.Rest.Resource.ExtensionResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ExtensionResourceCreate` {#TypeSpec.Rest.Resource.ExtensionResourceCreate} @@ -173,7 +173,7 @@ interface TypeSpec.Rest.Resource.ExtensionResourceList | Error +op TypeSpec.Rest.Resource.ExtensionResourceList.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ExtensionResourceOperations` {#TypeSpec.Rest.Resource.ExtensionResourceOperations} @@ -229,7 +229,7 @@ op TypeSpec.Rest.Resource.ExtensionResourceOperations.create(resource: TypeSpec. Lists all instances of the extension resource. ```typespec -op TypeSpec.Rest.Resource.ExtensionResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error +op TypeSpec.Rest.Resource.ExtensionResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ExtensionResourceRead` {#TypeSpec.Rest.Resource.ExtensionResourceRead} @@ -308,7 +308,7 @@ op TypeSpec.Rest.Resource.ResourceCollectionOperations.create(resource: TypeSpec Lists all instances of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error +op TypeSpec.Rest.Resource.ResourceCollectionOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ResourceCreate` {#TypeSpec.Rest.Resource.ResourceCreate} @@ -462,7 +462,7 @@ interface TypeSpec.Rest.Resource.ResourceList Lists all instances of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceList.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error +op TypeSpec.Rest.Resource.ResourceList.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ResourceOperations` {#TypeSpec.Rest.Resource.ResourceOperations} @@ -517,7 +517,7 @@ op TypeSpec.Rest.Resource.ResourceOperations.create(resource: TypeSpec.Rest.Reso Lists all instances of the resource. ```typespec -op TypeSpec.Rest.Resource.ResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error +op TypeSpec.Rest.Resource.ResourceOperations.list(): TypeSpec.Rest.Resource.CollectionWithNextLink | Error ``` ### `ResourceRead` {#TypeSpec.Rest.Resource.ResourceRead} From 5c9a1560726e0e5ecbabd3741ea4ef6a08ff6197 Mon Sep 17 00:00:00 2001 From: Will Temple Date: Wed, 13 Dec 2023 13:05:38 -0500 Subject: [PATCH 08/11] format --- packages/compiler/test/server/completion.test.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/compiler/test/server/completion.test.ts b/packages/compiler/test/server/completion.test.ts index 0e10df39ba..27a5a438fb 100644 --- a/packages/compiler/test/server/completion.test.ts +++ b/packages/compiler/test/server/completion.test.ts @@ -37,7 +37,10 @@ describe("compiler: server: completion", () => { label: "Record", insertText: "Record", kind: CompletionItemKind.Class, - documentation: { kind: MarkupKind.Markdown, value: "```typespec\nmodel Record\n```" }, + documentation: { + kind: MarkupKind.Markdown, + value: "```typespec\nmodel Record\n```", + }, }, ]); }); From 9013564a752cfb52b9f0a991f3e198dca1f2501f Mon Sep 17 00:00:00 2001 From: Will Temple Date: Mon, 18 Dec 2023 09:14:39 -0500 Subject: [PATCH 09/11] Renamed Property -> Element --- packages/compiler/lib/lib.tsp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/compiler/lib/lib.tsp b/packages/compiler/lib/lib.tsp index e656524348..fb2301aadf 100644 --- a/packages/compiler/lib/lib.tsp +++ b/packages/compiler/lib/lib.tsp @@ -146,10 +146,10 @@ model Array {} /** * @dev Model with string properties where all the properties have type `Property` - * @template Property The type of the properties + * @template Element The type of the properties */ -@indexer(string, Property) -model Record {} +@indexer(string, Element) +model Record {} /** * Represent a URL string as described by https://url.spec.whatwg.org/ From beaa509f669924cbd4df3805740f88b3847d58c9 Mon Sep 17 00:00:00 2001 From: Will Temple Date: Mon, 18 Dec 2023 09:56:43 -0500 Subject: [PATCH 10/11] Rebuilt and retested --- docs/standard-library/built-in-data-types.md | 4 ++-- packages/compiler/test/server/completion.test.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/standard-library/built-in-data-types.md b/docs/standard-library/built-in-data-types.md index 2b52f18677..c4971cec36 100644 --- a/docs/standard-library/built-in-data-types.md +++ b/docs/standard-library/built-in-data-types.md @@ -99,13 +99,13 @@ model OptionalProperties ```typespec -model Record +model Record ``` #### Template Parameters | Name | Description | |------|-------------| -| Property | The type of the properties | +| Element | The type of the properties | diff --git a/packages/compiler/test/server/completion.test.ts b/packages/compiler/test/server/completion.test.ts index 27a5a438fb..4777d56ddd 100644 --- a/packages/compiler/test/server/completion.test.ts +++ b/packages/compiler/test/server/completion.test.ts @@ -39,7 +39,7 @@ describe("compiler: server: completion", () => { kind: CompletionItemKind.Class, documentation: { kind: MarkupKind.Markdown, - value: "```typespec\nmodel Record\n```", + value: "```typespec\nmodel Record\n```", }, }, ]); From d665e8886ec7d9f39b7483276a739dd06a63043d Mon Sep 17 00:00:00 2001 From: Will Temple Date: Mon, 18 Dec 2023 10:06:33 -0500 Subject: [PATCH 11/11] Update some template docs --- docs/language-basics/built-in-types.md | 22 +++++++++++----------- docs/language-basics/documentation.md | 4 ++-- docs/language-basics/models.md | 4 ++-- docs/language-basics/scalars.md | 4 ++-- docs/language-basics/templates.md | 18 +++++++++--------- docs/language-basics/type-relations.md | 4 ++-- 6 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/language-basics/built-in-types.md b/docs/language-basics/built-in-types.md index a3d9e1d713..85fce70839 100644 --- a/docs/language-basics/built-in-types.md +++ b/docs/language-basics/built-in-types.md @@ -42,17 +42,17 @@ Built in types are related to each other according to the rules described in [ty ## Other core types -| Type | Description | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `bytes` | A sequence of bytes | -| `string` | A sequence of textual characters | -| `boolean` | Boolean with `true` and `false` values | -| `null` | Null value | -| `Array` | Array model type, equivalent to `T[]` | -| `Record` | Model with string keys where all the values have type `T` (similar to `Map` in TypeScript or `Dictionary` in .Net) | -| `unknown` | A top type in TypeSpec that all types can be assigned to. Values that can have any type should be assigned this value (similar to `any` in JavaScript) | -| `void` | A function/operation return type indicating the function/operation doesn't return a value. | -| `never` | The never type indicates the values that will never occur. | +| Type | Description | +| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `bytes` | A sequence of bytes | +| `string` | A sequence of textual characters | +| `boolean` | Boolean with `true` and `false` values | +| `null` | Null value | +| `Array` | Array model type, equivalent to `Element[]` | +| `Record` | Model with string keys where all the values have type `Element` (similar to `Map` in TypeScript or `Dictionary` in .Net) | +| `unknown` | A top type in TypeSpec that all types can be assigned to. Values that can have any type should be assigned this value (similar to `any` in JavaScript) | +| `void` | A function/operation return type indicating the function/operation doesn't return a value. | +| `never` | The never type indicates the values that will never occur. | ## String types diff --git a/docs/language-basics/documentation.md b/docs/language-basics/documentation.md index ee5fec89f7..14c823cc45 100644 --- a/docs/language-basics/documentation.md +++ b/docs/language-basics/documentation.md @@ -31,8 +31,8 @@ model Dog { The `@doc` decorator can also accept a source object which can be used, for example, to provide templated documentation for a generic type. ```typespec -@doc("Templated {name}", T) -model Template { +@doc("Templated {name}", Type) +model Template { } // doc will read "Templated A" diff --git a/docs/language-basics/models.md b/docs/language-basics/models.md index 3b78fd581d..9ddf6e9b35 100644 --- a/docs/language-basics/models.md +++ b/docs/language-basics/models.md @@ -164,9 +164,9 @@ model StringThing { [See templates](./templates.md) for details on templates ```typespec -model Page { +model Page { size: number; - item: T[]; + item: Item[]; } model DogPage { diff --git a/docs/language-basics/scalars.md b/docs/language-basics/scalars.md index bbf99d5b18..68de922f23 100644 --- a/docs/language-basics/scalars.md +++ b/docs/language-basics/scalars.md @@ -25,6 +25,6 @@ scalar Password extends string; Scalar support template parameters. Note: the only use for those template are decorators. ```typespec -@doc(T) -scalar Unreal; +@doc(Type) +scalar Unreal; ``` diff --git a/docs/language-basics/templates.md b/docs/language-basics/templates.md index 32dc5022d7..c909b72cf3 100644 --- a/docs/language-basics/templates.md +++ b/docs/language-basics/templates.md @@ -15,9 +15,9 @@ Templates can be used on: - [interfaces](./interfaces.md) ```typespec -model Page { +model Page { size: number; - item: T[]; + item: Item[]; } model DogPage { @@ -30,9 +30,9 @@ model DogPage { A template parameter can be given a default value with `= `. ```typespec -model Page { +model Page { size: number; - item: T[]; + item: Item[]; } ``` @@ -41,7 +41,7 @@ model Page { Template parameter can provide a constraint using the `extends` keyword. See [type relations](./type-relations.md) documentation for details on how validation works. ```typespec -alias Foo = T; +alias Foo = Type; ``` now instantiating Foo with the wrong type will result in an error @@ -54,15 +54,15 @@ alias Bar = Foo<123>; Template constraints can be a model expression ```typespec -// Expect T to be a model with property name: string -alias Foo = T; +// Expect Type to be a model with property name: string +alias Foo = Type; ``` Template parameter default also need to respect the constraint ```typespec -alias Foo = T +alias Foo = Type // Invalid -alias Bar = T +alias Bar = Type ^ Type '123' is not assignable to type 'TypeSpec.string' ``` diff --git a/docs/language-basics/type-relations.md b/docs/language-basics/type-relations.md index f4e6119dcc..b737b4fd72 100644 --- a/docs/language-basics/type-relations.md +++ b/docs/language-basics/type-relations.md @@ -9,9 +9,9 @@ title: Type relations ```mermaid graph RL - record["Record"] --> unknown + record["Record"] --> unknown customModel["Custom model with properties"] --> record["Record"] - array["Array"] --> unknown + array["Array"] --> unknown tuple["Tuple"] --> array numeric --> unknown subgraph numerics[For numeric types, a narrower type can be assigned to a wider one]