Rename template parameters for clarity and consistency (#2726)

This is in preparation for merging named template argument instantiation. --------- Co-authored-by: Will Temple <[email protected]>
microsoft · Dec 18, 2023 · aae7166 · aae7166
1 parent 6f68753
commit aae7166
Show file tree

Hide file tree

Showing 32 changed files with 695 additions and 586 deletions.
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
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "Rename template parameters in preparation for named template argument instantiation.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/compiler"
+}
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
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/http",
+      "comment": "Rename template parameters in preparation for named template argument instantiation.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/http"
+}
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
@@ -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"
+}
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
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/protobuf",
+      "comment": "Rename template parameters in preparation for named template argument instantiation.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/protobuf"
+}
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
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/rest",
+      "comment": "Rename template parameters in preparation for named template argument instantiation.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/rest"
+}
diff --git 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<T>`  | Array model type, equivalent to `T[]`                                                                                                                  |
-| `Record<T>` | Model with string keys where all the values have type `T` (similar to `Map<string, T>` in TypeScript or `Dictionary<string, T>` 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<Element>`  | Array model type, equivalent to `Element[]`                                                                                                                |
+| `Record<Element>` | Model with string keys where all the values have type `Element` (similar to `Map<string, Element>` in TypeScript or `Dictionary<string, Element>` 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
@@ -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<T extends {}>  {
+@doc("Templated {name}", Type)
+model Template<Type extends {}>  {
 }
 
 // doc will read "Templated A"

diff --git 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<T> {
+model Page<Item> {
   size: number;
-  item: T[];
+  item: Item[];
 }
 
 model DogPage {

diff --git 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<T extends string>;
+@doc(Type)
+scalar Unreal<Type extends string>;
 ```
diff --git 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<T> {
+model Page<Item> {
   size: number;
-  item: T[];
+  item: Item[];
 }
 
 model DogPage {
@@ -30,9 +30,9 @@ model DogPage {
 A template parameter can be given a default value with `= <value>`.
 
 ```typespec
-model Page<T = string> {
+model Page<Item = string> {
   size: number;
-  item: T[];
+  item: Item[];
 }
 ```
 
@@ -41,7 +41,7 @@ model Page<T = string> {
 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 extends string> = T;
+alias Foo<Type extends string> = 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 extends {name: string}> = T;
+// Expect Type to be a model with property name: string
+alias Foo<Type extends {name: string}> = Type;
 ```
 
 Template parameter default also need to respect the constraint
 
 ```typespec
-alias Foo<T extends string = "Abc">  = T
+alias Foo<Type extends string = "Abc">  = Type
 // Invalid
-alias Bar<T extends string = 123>  = T
+alias Bar<Type extends string = 123>  = 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
@@ -9,9 +9,9 @@ title: Type relations
 
 ```mermaid
 graph RL
-    record["Record<T>"] --> unknown
+    record["Record<Element>"] --> unknown
     customModel["Custom model with properties"] --> record["Record<T>"]
-    array["Array<T>"] --> unknown
+    array["Array<Element>"] --> unknown
     tuple["Tuple"] --> array
     numeric --> unknown
     subgraph numerics[For numeric types, a narrower type can be assigned to a wider one]

diff --git 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<TLocation, TName>
+model TypeSpec.Http.ApiKeyAuth<Location, Name>
 ```
 
 #### 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<T>
+model TypeSpec.Http.Body<Type>
 ```
 
 #### Template Parameters
 
 | Name | Description                              |
 | ---- | ---------------------------------------- |
-| T    | The type of the model's `body` property. |
+| Type | The type of the model's `body` property. |
 
 ### `ClientCredentialsFlow` {#TypeSpec.Http.ClientCredentialsFlow}
 
@@ -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<TFlows>
+model TypeSpec.Http.OAuth2Auth<Flows>
 ```
 
 #### Template Parameters
 
-| Name   | Description                        |
-| ------ | ---------------------------------- |
-| TFlows | The list of supported OAuth2 flows |
+| Name  | Description                        |
+| ----- | ---------------------------------- |
+| Flows | The list of supported OAuth2 flows |
 
 ### `OkResponse` {#TypeSpec.Http.OkResponse}
 
@@ -237,14 +238,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<T>
+model TypeSpec.Http.PlainData<Data>
 ```
 
 #### 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/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<T>
+model TypeSpec.JsonSchema.Json<Data>
 ```
 
 #### 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
@@ -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<T>` template. For example, `@extension("x-schema", { x: "value" })` will
+is wrapped in the `Json<Data>` 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<T>`. |
+| 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<Data>`. |
 
 ### `@id` {#@TypeSpec.JsonSchema.id}
 

diff --git 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<K, V>
+model TypeSpec.Protobuf.Map<Key, Value>
 ```
 
 #### 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}