diff --git a/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md b/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md new file mode 100644 index 0000000000..10ebce6ec4 --- /dev/null +++ b/.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md @@ -0,0 +1,13 @@ +--- +# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking +changeKind: internal +packages: + - "@typespec/http" + - "@typespec/openapi3" + - "@typespec/rest" + - "@typespec/json-schema" + - "@typespec/openapi" + - "@typespec/protobuf" + - "@typespec/versioning" +--- + diff --git a/.chronus/changes/ref-docs-models-2024-1-24-0-0-44.md b/.chronus/changes/ref-docs-models-2024-1-24-0-0-44.md new file mode 100644 index 0000000000..3bf9a27aca --- /dev/null +++ b/.chronus/changes/ref-docs-models-2024-1-24-0-0-44.md @@ -0,0 +1,8 @@ +--- +# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking +changeKind: fix +packages: + - "@typespec/compiler" +--- + +Wrap string in quotes in errors diff --git a/docs/libraries/http/reference/data-types.md b/docs/libraries/http/reference/data-types.md index fd6a41ca13..35dfc10b30 100644 --- a/docs/libraries/http/reference/data-types.md +++ b/docs/libraries/http/reference/data-types.md @@ -16,6 +16,12 @@ The request has been accepted for processing, but processing has not yet complet model TypeSpec.Http.AcceptedResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `202` | The status code. | + ### `ApiKeyAuth` {#TypeSpec.Http.ApiKeyAuth} An API key is a token that a client provides when making API calls. The key can be sent in the query string: @@ -49,6 +55,14 @@ model TypeSpec.Http.ApiKeyAuth | Location | The location of the API key | | Name | The name of the API key | +#### Properties + +| Name | Type | Description | +| ---- | ------------------------------- | ----------- | +| type | `TypeSpec.Http.AuthType.apiKey` | | +| in | `Location` | | +| name | `Name` | | + ### `AuthorizationCodeFlow` {#TypeSpec.Http.AuthorizationCodeFlow} Authorization Code flow @@ -57,6 +71,16 @@ Authorization Code flow model TypeSpec.Http.AuthorizationCodeFlow ``` +#### Properties + +| Name | Type | Description | +| ---------------- | ------------------------------------------------ | --------------------------------- | +| type | `TypeSpec.Http.OAuth2FlowType.authorizationCode` | authorization code flow | +| authorizationUrl | `string` | the authorization URL | +| tokenUrl | `string` | the token URL | +| refreshUrl? | `string` | the refresh URL | +| scopes? | `string[]` | list of scopes for the credential | + ### `BadRequestResponse` {#TypeSpec.Http.BadRequestResponse} The server could not understand the request due to invalid syntax. @@ -65,6 +89,12 @@ The server could not understand the request due to invalid syntax. model TypeSpec.Http.BadRequestResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `400` | The status code. | + ### `BasicAuth` {#TypeSpec.Http.BasicAuth} Basic authentication is a simple authentication scheme built into the HTTP protocol. @@ -79,6 +109,13 @@ Authorization: Basic ZGVtbzpwQDU1dzByZA== model TypeSpec.Http.BasicAuth ``` +#### Properties + +| Name | Type | Description | +| ------ | ----------------------------- | ------------------- | +| type | `TypeSpec.Http.AuthType.http` | Http authentication | +| scheme | `"basic"` | basic auth scheme | + ### `BearerAuth` {#TypeSpec.Http.BearerAuth} Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. @@ -93,6 +130,13 @@ Authorization: Bearer model TypeSpec.Http.BearerAuth ``` +#### Properties + +| Name | Type | Description | +| ------ | ----------------------------- | ------------------- | +| type | `TypeSpec.Http.AuthType.http` | Http authentication | +| scheme | `"bearer"` | bearer auth scheme | + ### `Body` {#TypeSpec.Http.Body} Defines a model with a single property of the given type, marked with `@body`. @@ -110,6 +154,12 @@ model TypeSpec.Http.Body | ---- | ---------------------------------------- | | Type | The type of the model's `body` property. | +#### Properties + +| Name | Type | Description | +| ---- | ------ | ----------- | +| body | `Type` | | + ### `ClientCredentialsFlow` {#TypeSpec.Http.ClientCredentialsFlow} Client credentials flow @@ -118,6 +168,15 @@ Client credentials flow model TypeSpec.Http.ClientCredentialsFlow ``` +#### Properties + +| Name | Type | Description | +| ----------- | ------------------------------------------------ | --------------------------------- | +| type | `TypeSpec.Http.OAuth2FlowType.clientCredentials` | client credential flow | +| tokenUrl | `string` | the token URL | +| refreshUrl? | `string` | the refresh URL | +| scopes? | `string[]` | list of scopes for the credential | + ### `ConflictResponse` {#TypeSpec.Http.ConflictResponse} The request conflicts with the current state of the server. @@ -126,6 +185,12 @@ The request conflicts with the current state of the server. model TypeSpec.Http.ConflictResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `409` | The status code. | + ### `CreatedResponse` {#TypeSpec.Http.CreatedResponse} The request has succeeded and a new resource has been created as a result. @@ -134,6 +199,12 @@ The request has succeeded and a new resource has been created as a result. model TypeSpec.Http.CreatedResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `201` | The status code. | + ### `ForbiddenResponse` {#TypeSpec.Http.ForbiddenResponse} Access is forbidden. @@ -142,6 +213,12 @@ Access is forbidden. model TypeSpec.Http.ForbiddenResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `403` | The status code. | + ### `HeaderOptions` {#TypeSpec.Http.HeaderOptions} Header options. @@ -150,6 +227,13 @@ Header options. model TypeSpec.Http.HeaderOptions ``` +#### Properties + +| Name | Type | Description | +| ------- | --------------------------------------------------------------------- | --------------------------------------------------------- | +| name? | `string` | Name of the header when sent over HTTP. | +| format? | `"csv" \| "multi" \| "tsv" \| "ssv" \| "pipes" \| "simple" \| "form"` | Determines the format of the array if type array is used. | + ### `ImplicitFlow` {#TypeSpec.Http.ImplicitFlow} Implicit flow @@ -158,6 +242,15 @@ Implicit flow model TypeSpec.Http.ImplicitFlow ``` +#### Properties + +| Name | Type | Description | +| ---------------- | --------------------------------------- | --------------------------------- | +| type | `TypeSpec.Http.OAuth2FlowType.implicit` | implicit flow | +| authorizationUrl | `string` | the authorization URL | +| refreshUrl? | `string` | the refresh URL | +| scopes? | `string[]` | list of scopes for the credential | + ### `LocationHeader` {#TypeSpec.Http.LocationHeader} The Location header contains the URL where the status of the long running operation can be checked. @@ -166,6 +259,12 @@ The Location header contains the URL where the status of the long running operat model TypeSpec.Http.LocationHeader ``` +#### Properties + +| Name | Type | Description | +| -------- | -------- | --------------------------------------------------------------------------------------------------- | +| location | `string` | The Location header contains the URL where the status of the long running operation can be checked. | + ### `MovedResponse` {#TypeSpec.Http.MovedResponse} The URL of the requested resource has been changed permanently. The new URL is given in the response. @@ -174,6 +273,13 @@ The URL of the requested resource has been changed permanently. The new URL is g model TypeSpec.Http.MovedResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | -------- | --------------------------------------------------------------------------------------------------- | +| statusCode | `301` | The status code. | +| location | `string` | The Location header contains the URL where the status of the long running operation can be checked. | + ### `NoAuth` {#TypeSpec.Http.NoAuth} This authentication option signifies that API is not secured at all. @@ -183,6 +289,12 @@ It might be useful when overriding authentication on interface of operation leve model TypeSpec.Http.NoAuth ``` +#### Properties + +| Name | Type | Description | +| ---- | ------------------------------- | ----------- | +| type | `TypeSpec.Http.AuthType.noAuth` | | + ### `NoContentResponse` {#TypeSpec.Http.NoContentResponse} There is no content to send for this request, but the headers may be useful. @@ -191,6 +303,12 @@ There is no content to send for this request, but the headers may be useful. model TypeSpec.Http.NoContentResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `204` | The status code. | + ### `NotFoundResponse` {#TypeSpec.Http.NotFoundResponse} The server cannot find the requested resource. @@ -199,6 +317,12 @@ The server cannot find the requested resource. model TypeSpec.Http.NotFoundResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `404` | The status code. | + ### `NotModifiedResponse` {#TypeSpec.Http.NotModifiedResponse} The client has made a conditional request and the resource has not been modified. @@ -207,6 +331,12 @@ The client has made a conditional request and the resource has not been modified model TypeSpec.Http.NotModifiedResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `304` | The status code. | + ### `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. @@ -226,6 +356,14 @@ model TypeSpec.Http.OAuth2Auth | Flows | The list of supported OAuth2 flows | | Scopes | The list of OAuth2 scopes, which are common for every flow from `Flows`. This list is combined with the scopes defined in specific OAuth2 flows. | +#### Properties + +| Name | Type | Description | +| ------------- | ------------------------------- | ----------- | +| type | `TypeSpec.Http.AuthType.oauth2` | | +| flows | `Flows` | | +| defaultScopes | `Scopes` | | + ### `OkResponse` {#TypeSpec.Http.OkResponse} The request has succeeded. @@ -234,6 +372,12 @@ The request has succeeded. model TypeSpec.Http.OkResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `200` | The status code. | + ### `OpenIdConnectAuth` {#TypeSpec.Http.OpenIdConnectAuth} OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol and supported by some OAuth 2.0 providers, such as Google and Azure Active Directory. @@ -255,6 +399,13 @@ model TypeSpec.Http.OpenIdConnectAuth | ---------- | ----------- | | ConnectUrl | | +#### Properties + +| Name | Type | Description | +| ---------------- | -------------------------------------- | ----------------------------------------------------------- | +| type | `TypeSpec.Http.AuthType.openIdConnect` | Auth type | +| openIdConnectUrl | `ConnectUrl` | Connect url. It can be specified relative to the server URL | + ### `PasswordFlow` {#TypeSpec.Http.PasswordFlow} Resource Owner Password flow @@ -263,6 +414,15 @@ Resource Owner Password flow model TypeSpec.Http.PasswordFlow ``` +#### Properties + +| Name | Type | Description | +| ---------------- | --------------------------------------- | --------------------------------- | +| type | `TypeSpec.Http.OAuth2FlowType.password` | password flow | +| authorizationUrl | `string` | the authorization URL | +| refreshUrl? | `string` | the refresh URL | +| scopes? | `string[]` | list of scopes for the credential | + ### `PlainData` {#TypeSpec.Http.PlainData} Produces a new model with the same properties as T, but with `@query`, @@ -278,6 +438,10 @@ model TypeSpec.Http.PlainData | ---- | -------------------------------------- | | Data | The model to spread as the plain data. | +#### Properties + +None + ### `QueryOptions` {#TypeSpec.Http.QueryOptions} Query parameter options. @@ -286,6 +450,13 @@ Query parameter options. model TypeSpec.Http.QueryOptions ``` +#### Properties + +| Name | Type | Description | +| ------- | --------------------------------------------------------------------- | --------------------------------------------------------- | +| name? | `string` | Name of the query when included in the url. | +| format? | `"multi" \| "csv" \| "ssv" \| "tsv" \| "simple" \| "form" \| "pipes"` | Determines the format of the array if type array is used. | + ### `Response` {#TypeSpec.Http.Response} Describes an HTTP response. @@ -300,6 +471,12 @@ model TypeSpec.Http.Response | ------ | -------------------------------- | | Status | The status code of the response. | +#### Properties + +| Name | Type | Description | +| ---------- | -------- | ----------- | +| statusCode | `Status` | | + ### `UnauthorizedResponse` {#TypeSpec.Http.UnauthorizedResponse} Access is unauthorized. @@ -308,6 +485,12 @@ Access is unauthorized. model TypeSpec.Http.UnauthorizedResponse ``` +#### Properties + +| Name | Type | Description | +| ---------- | ----- | ---------------- | +| statusCode | `401` | The status code. | + ### `ApiKeyLocation` {#TypeSpec.Http.ApiKeyLocation} Describes the location of the API key diff --git a/docs/libraries/http/reference/decorators.md b/docs/libraries/http/reference/decorators.md index db907c0fe2..f9025ae3ba 100644 --- a/docs/libraries/http/reference/decorators.md +++ b/docs/libraries/http/reference/decorators.md @@ -113,9 +113,9 @@ Specify this property is to be sent or received as an HTTP header. #### Parameters -| Name | Type | Description | -| ------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| headerNameOrOptions | `union string \| TypeSpec.Http.HeaderOptions` | Optional name of the header when sent over HTTP or header options.
By default the header name will be the property name converted from camelCase to kebab-case. (e.g. `contentType` -> `content-type`) | +| Name | Type | Description | +| ------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| headerNameOrOptions | `string \| TypeSpec.Http.HeaderOptions` | Optional name of the header when sent over HTTP or header options.
By default the header name will be the property name converted from camelCase to kebab-case. (e.g. `contentType` -> `content-type`) | #### Examples @@ -151,13 +151,13 @@ Specify if inapplicable metadata should be included in the payload for the given #### Target -`(intrinsic) unknown` +`unknown` #### Parameters -| Name | Type | Description | -| ----- | ------------------------ | --------------------------------------------------------------- | -| value | `valueof scalar boolean` | If true, inapplicable metadata will be included in the payload. | +| Name | Type | Description | +| ----- | ----------------- | --------------------------------------------------------------- | +| value | `valueof boolean` | If true, inapplicable metadata will be included in the payload. | ### `@patch` {#@TypeSpec.Http.patch} @@ -195,9 +195,9 @@ Explicitly specify that this property is to be interpolated as a path parameter. #### Parameters -| Name | Type | Description | -| --------- | ----------------------- | --------------------------------------------------- | -| paramName | `valueof scalar string` | Optional name of the parameter in the url template. | +| Name | Type | Description | +| --------- | ---------------- | --------------------------------------------------- | +| paramName | `valueof string` | Optional name of the parameter in the url template. | #### Examples @@ -264,9 +264,9 @@ Specify this property is to be sent as a query parameter. #### Parameters -| Name | Type | Description | -| ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------- | -| queryNameOrOptions | `union string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. | +| Name | Type | Description | +| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------- | +| queryNameOrOptions | `string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. | #### Examples @@ -297,14 +297,14 @@ it will be used as a prefix to the route URI of the operation. #### Target -`union Namespace | Interface | Operation` +`Namespace | Interface | Operation` #### Parameters -| Name | Type | Description | -| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| path | `valueof scalar string` | Relative route path. Cannot include query parameters. | -| options | `model (anonymous model)` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| Name | Type | Description | +| ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| path | `valueof string` | Relative route path. Cannot include query parameters. | +| options | `{...}` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | #### Examples @@ -327,11 +327,11 @@ Specify the endpoint for this service. #### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ------------------------------------------------------- | -| url | `valueof scalar string` | Server endpoint | -| description | `valueof scalar string` | Description of the endpoint | -| parameters | `model Record` | Optional set of parameters used to interpolate the url. | +| Name | Type | Description | +| ----------- | ----------------- | ------------------------------------------------------- | +| url | `valueof string` | Server endpoint | +| description | `valueof string` | Description of the endpoint | +| parameters | `Record` | Optional set of parameters used to interpolate the url. | #### Examples @@ -410,13 +410,13 @@ Specify authentication for a whole service or specific methods. See the [documen #### Target -`union Namespace | Interface | Operation` +`Namespace | Interface | Operation` #### Parameters -| Name | Type | Description | -| ---- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| auth | `union {} \| Union \| {}[]` | Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple (must use all authentication together) | +| Name | Type | Description | +| ---- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| auth | `{} \| Union \| {}[]` | Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple (must use all authentication together) | #### Examples diff --git a/docs/libraries/json-schema/reference/data-types.md b/docs/libraries/json-schema/reference/data-types.md index 385b1d1a99..845b3e54b8 100644 --- a/docs/libraries/json-schema/reference/data-types.md +++ b/docs/libraries/json-schema/reference/data-types.md @@ -23,6 +23,12 @@ model TypeSpec.JsonSchema.Json | ---- | ------------------------------- | | Data | the type to convert to raw JSON | +#### Properties + +| Name | Type | Description | +| ----- | ------ | ----------- | +| value | `Data` | | + ### `Format` {#TypeSpec.JsonSchema.Format} Well-known JSON Schema formats. diff --git a/docs/libraries/json-schema/reference/decorators.md b/docs/libraries/json-schema/reference/decorators.md index cf75aea96c..a61dd90562 100644 --- a/docs/libraries/json-schema/reference/decorators.md +++ b/docs/libraries/json-schema/reference/decorators.md @@ -22,9 +22,9 @@ Set the base URI for any schemas emitted from types within this namespace. #### Parameters -| Name | Type | Description | -| ------- | ----------------------- | ------------------------------------------------------------------------ | -| baseUri | `valueof scalar string` | the base URI. Schema IDs inside this namespace are relative to this URI. | +| Name | Type | Description | +| ------- | ---------------- | ------------------------------------------------------------------------ | +| baseUri | `valueof string` | the base URI. Schema IDs inside this namespace are relative to this URI. | ### `@contains` {#@TypeSpec.JsonSchema.contains} @@ -37,13 +37,13 @@ Use `@minContains` and `@maxContains` to customize how many instances to expect. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | --------------------- | -------------------------------- | -| value | `(intrinsic) unknown` | The type the array must contain. | +| Name | Type | Description | +| ----- | --------- | -------------------------------- | +| value | `unknown` | The type the array must contain. | ### `@contentEncoding` {#@TypeSpec.JsonSchema.contentEncoding} @@ -55,13 +55,13 @@ Specify the encoding used for the contents of a string. #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ----------- | -| value | `valueof scalar string` |
| +| Name | Type | Description | +| ----- | ---------------- | ----------- | +| value | `valueof string` |
| ### `@contentMediaType` {#@TypeSpec.JsonSchema.contentMediaType} @@ -73,13 +73,13 @@ Specify the content type of content stored in a string. #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ------------------------------------- | -| value | `valueof scalar string` | the media type of the string contents | +| Name | Type | Description | +| ----- | ---------------- | ------------------------------------- | +| value | `valueof string` | the media type of the string contents | ### `@contentSchema` {#@TypeSpec.JsonSchema.contentSchema} @@ -92,13 +92,13 @@ media type and encoding. #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | --------------------- | --------------------------------- | -| value | `(intrinsic) unknown` | the schema of the string contents | +| Name | Type | Description | +| ----- | --------- | --------------------------------- | +| value | `unknown` | the schema of the string contents | ### `@extension` {#@TypeSpec.JsonSchema.extension} @@ -114,14 +114,14 @@ emit the raw JSON code `{x: "value"}`. #### Target -`(intrinsic) unknown` +`unknown` #### 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 string` | the name of the keyword of vendor extension, e.g. `x-custom`. | +| value | `unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | ### `@id` {#@TypeSpec.JsonSchema.id} @@ -136,13 +136,13 @@ By default, the id will be constructed based on the declaration's name. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ----------------------------------------------- | -| id | `valueof scalar string` | the id of the JSON schema for this declaration. | +| Name | Type | Description | +| ---- | ---------------- | ----------------------------------------------- | +| id | `valueof string` | the id of the JSON schema for this declaration. | ### `@jsonSchema` {#@TypeSpec.JsonSchema.jsonSchema} @@ -158,13 +158,13 @@ you can provide the id. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters -| Name | Type | Description | -| ------- | ----------------------- | --------------------------------------------------- | -| baseUri | `valueof scalar string` | Schema IDs are interpreted as relative to this URI. | +| Name | Type | Description | +| ------- | ---------------- | --------------------------------------------------- | +| baseUri | `valueof string` | Schema IDs are interpreted as relative to this URI. | ### `@maxContains` {#@TypeSpec.JsonSchema.maxContains} @@ -177,13 +177,13 @@ by the contains decorator. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The maximum number of instances the array must contain | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The maximum number of instances the array must contain | ### `@maxProperties` {#@TypeSpec.JsonSchema.maxProperties} @@ -195,13 +195,13 @@ Specify the maximum number of properties this object can have. #### Target -`union Record | ModelProperty` +`Record | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The maximum number of properties this object can have. | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The maximum number of properties this object can have. | ### `@minContains` {#@TypeSpec.JsonSchema.minContains} @@ -214,13 +214,13 @@ by the contains decorator. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The minimum number of instances the array must contain | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The minimum number of instances the array must contain | ### `@minProperties` {#@TypeSpec.JsonSchema.minProperties} @@ -232,13 +232,13 @@ Specify the minimum number of properties this object can have. #### Target -`union Record | ModelProperty` +`Record | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The minimum number of properties this object can have. | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The minimum number of properties this object can have. | ### `@multipleOf` {#@TypeSpec.JsonSchema.multipleOf} @@ -250,13 +250,13 @@ Specify that the numeric type must be a multiple of some numeric value. #### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ------------------------ | -------------------------------------------------- | -| value | `valueof scalar numeric` | The numeric type must be a multiple of this value. | +| Name | Type | Description | +| ----- | ----------------- | -------------------------------------------------- | +| value | `valueof numeric` | The numeric type must be a multiple of this value. | ### `@prefixItems` {#@TypeSpec.JsonSchema.prefixItems} @@ -268,13 +268,13 @@ Specify that the target array must begin with the provided types. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters -| Name | Type | Description | -| ----- | ----------------- | --------------------------------------------------------------------------- | -| value | `model unknown[]` | a tuple containing the types that must be present at the start of the array | +| Name | Type | Description | +| ----- | ----------- | --------------------------------------------------------------------------- | +| value | `unknown[]` | a tuple containing the types that must be present at the start of the array | ### `@uniqueItems` {#@TypeSpec.JsonSchema.uniqueItems} @@ -286,7 +286,7 @@ Specify that every item in the array must be unique. #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters diff --git a/docs/libraries/openapi/reference/data-types.md b/docs/libraries/openapi/reference/data-types.md index 0a0fd0d0b5..04831f5d81 100644 --- a/docs/libraries/openapi/reference/data-types.md +++ b/docs/libraries/openapi/reference/data-types.md @@ -16,6 +16,17 @@ Additional information for the OpenAPI document. model TypeSpec.OpenAPI.AdditionalInfo ``` +#### Properties + +| Name | Type | Description | +| --------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| title? | `string` | The title of the API. Overrides the `@service` title. | +| summary? | `string` | A short summary of the API. Overrides the `@summary` provided on the service namespace. | +| version? | `string` | The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version). | +| termsOfService? | `url` | A URL to the Terms of Service for the API. MUST be in the format of a URL. | +| contact? | [`Contact`](./data-types.md#TypeSpec.OpenAPI.Contact) | The contact information for the exposed API. | +| license? | [`License`](./data-types.md#TypeSpec.OpenAPI.License) | The license information for the exposed API. | + ### `Contact` {#TypeSpec.OpenAPI.Contact} Contact information for the exposed API. @@ -24,6 +35,14 @@ Contact information for the exposed API. model TypeSpec.OpenAPI.Contact ``` +#### Properties + +| Name | Type | Description | +| ------ | -------- | ------------------------------------------------------------------------------------------------ | +| name? | `string` | The identifying name of the contact person/organization. | +| url? | `url` | The URL pointing to the contact information. MUST be in the format of a URL. | +| email? | `string` | The email address of the contact person/organization. MUST be in the format of an email address. | + ### `License` {#TypeSpec.OpenAPI.License} License information for the exposed API. @@ -31,3 +50,10 @@ License information for the exposed API. ```typespec model TypeSpec.OpenAPI.License ``` + +#### Properties + +| Name | Type | Description | +| ---- | -------- | ---------------------------------------------------------------------- | +| name | `string` | The license name used for the API. | +| url? | `url` | A URL to the license used for the API. MUST be in the format of a URL. | diff --git a/docs/libraries/openapi/reference/decorators.md b/docs/libraries/openapi/reference/decorators.md index 44ae2d91da..90b23016bb 100644 --- a/docs/libraries/openapi/reference/decorators.md +++ b/docs/libraries/openapi/reference/decorators.md @@ -44,14 +44,14 @@ Attach some custom data to the OpenAPI element generated from this type. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ----------------------------------- | -| key | `valueof scalar string` | Extension key. Must start with `x-` | -| value | `(intrinsic) unknown` | Extension value. | +| Name | Type | Description | +| ----- | ---------------- | ----------------------------------- | +| key | `valueof string` | Extension key. Must start with `x-` | +| value | `unknown` | Extension value. | #### Examples @@ -76,14 +76,14 @@ Specify the OpenAPI `externalDocs` property for this type. #### Target -`(intrinsic) unknown` +`unknown` #### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ----------------------- | -| url | `valueof scalar string` | Url to the docs | -| description | `valueof scalar string` | Description of the docs | +| Name | Type | Description | +| ----------- | ---------------- | ----------------------- | +| url | `valueof string` | Url to the docs | +| description | `valueof string` | Description of the docs | #### Examples @@ -110,9 +110,9 @@ The service `title` and `version` are already specified using `@service`. #### Parameters -| Name | Type | Description | -| -------------- | --------------------------------------- | ---------------------- | -| additionalInfo | `model TypeSpec.OpenAPI.AdditionalInfo` | Additional information | +| Name | Type | Description | +| -------------- | ------------------------------------------------------------------- | ---------------------- | +| additionalInfo | [`AdditionalInfo`](./data-types.md#TypeSpec.OpenAPI.AdditionalInfo) | Additional information | ### `@operationId` {#@TypeSpec.OpenAPI.operationId} @@ -128,9 +128,9 @@ Specify the OpenAPI `operationId` property for this operation. #### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ------------------- | -| operationId | `valueof scalar string` | Operation id value. | +| Name | Type | Description | +| ----------- | ---------------- | ------------------- | +| operationId | `valueof string` | Operation id value. | #### Examples diff --git a/docs/libraries/openapi3/reference/decorators.md b/docs/libraries/openapi3/reference/decorators.md index eefd6469cc..c377176b73 100644 --- a/docs/libraries/openapi3/reference/decorators.md +++ b/docs/libraries/openapi3/reference/decorators.md @@ -18,7 +18,7 @@ Specify that `oneOf` should be used instead of `anyOf` for that union. #### Target -`union Union | ModelProperty` +`Union | ModelProperty` #### Parameters @@ -34,10 +34,10 @@ Specify an external reference that should be used inside of emitting this type. #### Target -`union Model | ModelProperty` +`Model | ModelProperty` #### Parameters -| Name | Type | Description | -| ---- | ----------------------- | -------------------------------------------------------------------- | -| ref | `valueof scalar string` | External reference(e.g. "../../common.json#/components/schemas/Foo") | +| Name | Type | Description | +| ---- | ---------------- | -------------------------------------------------------------------- | +| ref | `valueof string` | External reference(e.g. "../../common.json#/components/schemas/Foo") | diff --git a/docs/libraries/protobuf/reference/data-types.md b/docs/libraries/protobuf/reference/data-types.md index 3c12f0f9f7..846a8b5c55 100644 --- a/docs/libraries/protobuf/reference/data-types.md +++ b/docs/libraries/protobuf/reference/data-types.md @@ -40,6 +40,12 @@ model TypeSpec.Protobuf.Extern model Widget is Extern<"path/to/test.proto", "test.Widget">; ``` +#### Properties + +| Name | Type | Description | +| -------- | ------- | ----------- | +| \_extern | `never` | | + ### `Map` {#TypeSpec.Protobuf.Map} A type representing a Protobuf `map`. Instances of this type in models will be converted to the built-in `map` type @@ -59,6 +65,10 @@ model TypeSpec.Protobuf.Map | Key | the key type (any integral type or string) | | Value | the value type (any type other than another map) | +#### Properties + +None + ### `PackageDetails` {#TypeSpec.Protobuf.PackageDetails} Details applied to a package definition by the [`@package`](./decorators# @@ -67,6 +77,13 @@ Details applied to a package definition by the [`@package`](./decorators# model TypeSpec.Protobuf.PackageDetails ``` +#### Properties + +| Name | Type | Description | +| -------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name? | `string` | The package's name.

By default, the package's name is constructed from the namespace it is applied to. | +| options? | `Record` | The package's top-level options.

See the [Protobuf Language Guide - Options](https://protobuf.dev/programming-guides/proto3/#options) for more information.

Currently, only string, boolean, and numeric options are supported. | + ### `StreamMode` {#TypeSpec.Protobuf.StreamMode} The streaming mode of an operation. One of: @@ -166,6 +183,12 @@ This model references `google.protobuf.Any` from `google/protobuf/any.proto`. model TypeSpec.Protobuf.WellKnown.Any ``` +#### Properties + +| Name | Type | Description | +| -------- | ------- | ----------- | +| \_extern | `never` | | + ### `Empty` {#TypeSpec.Protobuf.WellKnown.Empty} An empty message. @@ -176,6 +199,12 @@ This model references `google.protobuf.Empty` from `google/protobuf/empty.proto` model TypeSpec.Protobuf.WellKnown.Empty ``` +#### Properties + +| Name | Type | Description | +| -------- | ------- | ----------- | +| \_extern | `never` | | + ### `LatLng` {#TypeSpec.Protobuf.WellKnown.LatLng} A latitude and longitude. @@ -186,6 +215,12 @@ This model references `google.type.LatLng` from `google/type/latlng.proto`. model TypeSpec.Protobuf.WellKnown.LatLng ``` +#### Properties + +| Name | Type | Description | +| -------- | ------- | ----------- | +| \_extern | `never` | | + ### `Timestamp` {#TypeSpec.Protobuf.WellKnown.Timestamp} A timestamp. @@ -195,3 +230,9 @@ This model references `google.protobuf.Timestamp` from `google/protobuf/timestam ```typespec model TypeSpec.Protobuf.WellKnown.Timestamp ``` + +#### Properties + +| Name | Type | Description | +| -------- | ------- | ----------- | +| \_extern | `never` | | diff --git a/docs/libraries/protobuf/reference/decorators.md b/docs/libraries/protobuf/reference/decorators.md index 7ec642c0fe..1491b78bf6 100644 --- a/docs/libraries/protobuf/reference/decorators.md +++ b/docs/libraries/protobuf/reference/decorators.md @@ -29,9 +29,9 @@ The field index of a Protobuf message must: #### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ------------------------------------ | -| index | `valueof scalar uint32` | The whole-number index of the field. | +| Name | Type | Description | +| ----- | ---------------- | ------------------------------------ | +| index | `valueof uint32` | The whole-number index of the field. | #### Examples @@ -59,7 +59,7 @@ This decorator will force the emitter to check and emit a model. #### Target -`model {}` +`{}` #### Parameters @@ -80,9 +80,9 @@ single Protobuf file. #### Parameters -| Name | Type | Description | -| ------- | ---------------------------------------- | ----------------------------------- | -| details | `model TypeSpec.Protobuf.PackageDetails` | the optional details of the package | +| Name | Type | Description | +| ------- | -------------------------------------------------------------------- | ----------------------------------- | +| details | [`PackageDetails`](./data-types.md#TypeSpec.Protobuf.PackageDetails) | the optional details of the package | ### `@reserve` {#@TypeSpec.Protobuf.reserve} @@ -113,13 +113,13 @@ information. #### Target -`model {}` +`{}` #### Parameters -| Name | Type | Description | -| ------------ | ------------------------------------------------------ | ---------------------------- | -| reservations | `valueof model string \| [uint32, uint32] \| uint32[]` | a list of field reservations | +| Name | Type | Description | +| ------------ | ------------------------------------------------ | ---------------------------- | +| reservations | `valueof string \| [uint32, uint32] \| uint32[]` | a list of field reservations | #### Examples @@ -162,9 +162,9 @@ Set the streaming mode of an operation. See [StreamMode](./data-types#TypeSpec.P #### Parameters -| Name | Type | Description | -| ---- | ----------------------------------- | ---------------------------------------------- | -| mode | `enum TypeSpec.Protobuf.StreamMode` | The streaming mode to apply to this operation. | +| Name | Type | Description | +| ---- | ------------------------------------------------------------ | ---------------------------------------------- | +| mode | [`StreamMode`](./data-types.md#TypeSpec.Protobuf.StreamMode) | The streaming mode to apply to this operation. | #### Examples diff --git a/docs/libraries/rest/reference/data-types.md b/docs/libraries/rest/reference/data-types.md index b179018191..6b1dcd5d1e 100644 --- a/docs/libraries/rest/reference/data-types.md +++ b/docs/libraries/rest/reference/data-types.md @@ -35,6 +35,13 @@ model TypeSpec.Rest.Resource.CollectionWithNextLink | -------- | ------------------------------------ | | Resource | The resource type of the collection. | +#### Properties + +| Name | Type | Description | +| --------- | -------------------------------- | ----------- | +| value | `Array` | | +| nextLink? | `TypeSpec.Rest.ResourceLocation` | | + ### `KeysOf` {#TypeSpec.Rest.Resource.KeysOf} Dynamically gathers keys of the model type `Resource`. @@ -49,6 +56,10 @@ model TypeSpec.Rest.Resource.KeysOf | -------- | -------------------------- | | Resource | The target resource model. | +#### Properties + +None + ### `ParentKeysOf` {#TypeSpec.Rest.Resource.ParentKeysOf} Dynamically gathers parent keys of the model type `Resource`. @@ -63,6 +74,10 @@ model TypeSpec.Rest.Resource.ParentKeysOf | -------- | -------------------------- | | Resource | The target resource model. | +#### Properties + +None + ### `ResourceCollectionParameters` {#TypeSpec.Rest.Resource.ResourceCollectionParameters} Represents collection operation parameters for the resource of type `Resource`. @@ -77,6 +92,10 @@ model TypeSpec.Rest.Resource.ResourceCollectionParameters | -------- | ------------------- | | Resource | The resource model. | +#### Properties + +None + ### `ResourceCreatedResponse` {#TypeSpec.Rest.Resource.ResourceCreatedResponse} Resource create operation completed successfully. @@ -91,6 +110,13 @@ model TypeSpec.Rest.Resource.ResourceCreatedResponse | -------- | ------------------------------------ | | Resource | The resource model that was created. | +#### Properties + +| Name | Type | Description | +| ---------- | ---------- | ---------------- | +| statusCode | `201` | The status code. | +| body | `Resource` | | + ### `ResourceCreateModel` {#TypeSpec.Rest.Resource.ResourceCreateModel} Resource create operation model. @@ -105,6 +131,10 @@ model TypeSpec.Rest.Resource.ResourceCreateModel | -------- | ----------------------------- | | Resource | The resource model to create. | +#### Properties + +None + ### `ResourceCreateOrUpdateModel` {#TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel} Resource create or update operation model. @@ -119,6 +149,10 @@ model TypeSpec.Rest.Resource.ResourceCreateOrUpdateModel | -------- | --------------------------------------- | | Resource | The resource model to create or update. | +#### Properties + +None + ### `ResourceDeletedResponse` {#TypeSpec.Rest.Resource.ResourceDeletedResponse} Resource deleted successfully. @@ -127,6 +161,12 @@ Resource deleted successfully. model TypeSpec.Rest.Resource.ResourceDeletedResponse ``` +#### Properties + +| Name | Type | Description | +| ---- | ----- | ---------------- | +| \_ | `200` | The status code. | + ### `ResourceError` {#TypeSpec.Rest.Resource.ResourceError} The default error response for resource operations. @@ -135,6 +175,13 @@ The default error response for resource operations. model TypeSpec.Rest.Resource.ResourceError ``` +#### Properties + +| Name | Type | Description | +| ------- | -------- | ------------------ | +| code | `int32` | The error code. | +| message | `string` | The error message. | + ### `ResourceParameters` {#TypeSpec.Rest.Resource.ResourceParameters} Represents operation parameters for the resource of type `Resource`. @@ -148,3 +195,7 @@ model TypeSpec.Rest.Resource.ResourceParameters | Name | Description | | -------- | ------------------- | | Resource | The resource model. | + +#### Properties + +None diff --git a/docs/libraries/rest/reference/decorators.md b/docs/libraries/rest/reference/decorators.md index 5163353f55..39ec842b5a 100644 --- a/docs/libraries/rest/reference/decorators.md +++ b/docs/libraries/rest/reference/decorators.md @@ -22,27 +22,27 @@ Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my #### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ----------------------------------------------------------------------------- | -| name | `valueof scalar string` | Name of the action. If not specified, the name of the operation will be used. | +| Name | Type | Description | +| ---- | ---------------- | ----------------------------------------------------------------------------- | +| name | `valueof string` | Name of the action. If not specified, the name of the operation will be used. | ### `@actionSeparator` {#@TypeSpec.Rest.actionSeparator} Defines the separator string that is inserted before the action name in auto-generated routes for actions. ```typespec -@TypeSpec.Rest.actionSeparator(seperator: valueof / | : | /:) +@TypeSpec.Rest.actionSeparator(seperator: valueof "/" | ":" | "/:") ``` #### Target -`union Model | ModelProperty | Operation` +`Model | ModelProperty | Operation` #### Parameters | Name | Type | Description | | --------- | ---------------------------- | ---------------------------------------------------------------- | -| seperator | `valueof union / \| : \| /:` | Seperator seperating the action segment from the rest of the url | +| seperator | `valueof "/" \| ":" \| "/:"` | Seperator seperating the action segment from the rest of the url | ### `@autoRoute` {#@TypeSpec.Rest.autoRoute} @@ -54,7 +54,7 @@ This interface or operation should resolve its route automatically. To be used w #### Target -`union Interface | Operation` +`Interface | Operation` #### Parameters @@ -83,10 +83,10 @@ Specify this operation is a collection action. (Scopped to a resource, /pets/my- #### Parameters -| Name | Type | Description | -| ------------ | ----------------------- | ----------------------------------------------------------------------------- | -| resourceType | `Model` | Resource marked with | -| name | `valueof scalar string` | Name of the action. If not specified, the name of the operation will be used. | +| Name | Type | Description | +| ------------ | ---------------- | ----------------------------------------------------------------------------- | +| resourceType | `Model` | Resource marked with | +| name | `valueof string` | Name of the action. If not specified, the name of the operation will be used. | ### `@copyResourceKeyParameters` {#@TypeSpec.Rest.copyResourceKeyParameters} @@ -102,9 +102,9 @@ Copy the resource key parameters on the model #### Parameters -| Name | Type | Description | -| ------ | ----------------------- | ------------------------------------- | -| filter | `valueof scalar string` | Filter to exclude certain properties. | +| Name | Type | Description | +| ------ | ---------------- | ------------------------------------- | +| filter | `valueof string` | Filter to exclude certain properties. | ### `@createsOrReplacesResource` {#@TypeSpec.Rest.createsOrReplacesResource} @@ -246,9 +246,9 @@ Mark this model as a resource type with a name. #### Parameters -| Name | Type | Description | -| -------------- | ----------------------- | ---------------------- | -| collectionName | `valueof scalar string` | type's collection name | +| Name | Type | Description | +| -------------- | ---------------- | ---------------------- | +| collectionName | `valueof string` | type's collection name | ### `@segment` {#@TypeSpec.Rest.segment} @@ -260,13 +260,13 @@ Defines the preceding path segment for a #### Target -`union Model | ModelProperty | Operation` +`Model | ModelProperty | Operation` #### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ---------------------------------------------------------------------------------------------- | -| name | `valueof scalar string` | Segment that will be inserted into the operation route before the path parameter's name field. | +| Name | Type | Description | +| ---- | ---------------- | ---------------------------------------------------------------------------------------------- | +| name | `valueof string` | Segment that will be inserted into the operation route before the path parameter's name field. | #### Examples diff --git a/docs/libraries/versioning/reference/decorators.md b/docs/libraries/versioning/reference/decorators.md index 1f752c8b5a..08da695b58 100644 --- a/docs/libraries/versioning/reference/decorators.md +++ b/docs/libraries/versioning/reference/decorators.md @@ -18,7 +18,7 @@ Identifies when the target was added. #### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` #### Parameters @@ -82,7 +82,7 @@ Identifies when the target was removed. #### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` #### Parameters @@ -117,14 +117,14 @@ Identifies when the target has been renamed. #### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` #### Parameters -| Name | Type | Description | -| ------- | ----------------------- | ------------------------------------------- | -| version | `EnumMember` | The version that the target was renamed in. | -| oldName | `valueof scalar string` | The previous name of the target. | +| Name | Type | Description | +| ------- | ---------------- | ------------------------------------------- | +| version | `EnumMember` | The version that the target was renamed in. | +| oldName | `valueof string` | The previous name of the target. | #### Examples @@ -147,10 +147,10 @@ Identifies when the target type changed. #### Parameters -| Name | Type | Description | -| ------- | --------------------- | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `(intrinsic) unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | -------------------------------------------- | +| version | `EnumMember` | The version that the target type changed in. | +| oldType | `unknown` | The previous type of the target. | ### `@typeChangedFrom` {#@TypeSpec.Versioning.typeChangedFrom} @@ -166,10 +166,10 @@ Identifies when the target type changed. #### Parameters -| Name | Type | Description | -| ------- | --------------------- | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `(intrinsic) unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | -------------------------------------------- | +| version | `EnumMember` | The version that the target type changed in. | +| oldType | `unknown` | The previous type of the target. | ### `@useDependency` {#@TypeSpec.Versioning.useDependency} @@ -181,13 +181,13 @@ Identifies that a namespace or a given versioning enum member relies upon a vers #### Target -`union EnumMember | Namespace` +`EnumMember | Namespace` #### Parameters -| Name | Type | Description | -| -------------- | -------------------- | --------------------------------------------------------------------- | -| versionRecords | `model EnumMember[]` | The dependent library version(s) for the target namespace or version. | +| Name | Type | Description | +| -------------- | -------------- | --------------------------------------------------------------------- | +| versionRecords | `EnumMember[]` | The dependent library version(s) for the target namespace or version. | #### Examples diff --git a/docs/standard-library/built-in-data-types.md b/docs/standard-library/built-in-data-types.md index c4971cec36..719158cd91 100644 --- a/docs/standard-library/built-in-data-types.md +++ b/docs/standard-library/built-in-data-types.md @@ -9,7 +9,6 @@ toc_max_heading_level: 3 - ```typespec model Array ``` @@ -20,11 +19,12 @@ model Array | Element | The type of the array elements | +#### Properties +None ### `DefaultKeyVisibility` {#DefaultKeyVisibility} Applies a visibility setting to a collection of properties. - ```typespec model DefaultKeyVisibility ``` @@ -36,21 +36,23 @@ model DefaultKeyVisibility | Visibility | The visibility to apply to all properties. | +#### Properties +None ### `object` {#object} Represent a model - ```typespec model object ``` +#### Properties +None ### `OmitDefaults` {#OmitDefaults} Represents a collection of properties with default values omitted. - ```typespec model OmitDefaults ``` @@ -61,11 +63,12 @@ model OmitDefaults | Source | An object whose spread property defaults are all omitted. | +#### Properties +None ### `OmitProperties` {#OmitProperties} Represents a collection of omitted properties. - ```typespec model OmitProperties ``` @@ -77,11 +80,12 @@ model OmitProperties | Keys | The property keys to omit. | +#### Properties +None ### `OptionalProperties` {#OptionalProperties} Represents a collection of optional properties. - ```typespec model OptionalProperties ``` @@ -92,12 +96,13 @@ model OptionalProperties | Source | An object whose spread properties are all optional. | +#### Properties +None ### `Record` {#Record} - ```typespec model Record ``` @@ -108,21 +113,26 @@ model Record | Element | The type of the properties | +#### Properties +None ### `ServiceOptions` {#ServiceOptions} Service options. - ```typespec model ServiceOptions ``` +#### Properties +| Name | Type | Description | +|------|------|-------------| +| title? | [`string`](#string) | Title of the service. | +| version? | [`string`](#string) | Version of the service. | ### `UpdateableProperties` {#UpdateableProperties} Represents a collection of updateable properties. - ```typespec model UpdateableProperties ``` @@ -133,11 +143,12 @@ model UpdateableProperties | Source | An object whose spread properties are all updateable. | +#### Properties +None ### `BytesKnownEncoding` {#BytesKnownEncoding} Known encoding to use on bytes - ```typespec enum BytesKnownEncoding ``` @@ -147,7 +158,6 @@ enum BytesKnownEncoding ### `DateTimeKnownEncoding` {#DateTimeKnownEncoding} Known encoding to use on utcDateTime or offsetDateTime - ```typespec enum DateTimeKnownEncoding ``` @@ -157,7 +167,6 @@ enum DateTimeKnownEncoding ### `DurationKnownEncoding` {#DurationKnownEncoding} Known encoding to use on duration - ```typespec enum DurationKnownEncoding ``` @@ -167,7 +176,6 @@ enum DurationKnownEncoding ### `boolean` {#boolean} Boolean with `true` and `false` values. - ```typespec scalar boolean ``` @@ -177,7 +185,6 @@ scalar boolean ### `bytes` {#bytes} Represent a byte array - ```typespec scalar bytes ``` @@ -188,7 +195,6 @@ scalar bytes A decimal number with any length and precision. This represent any `decimal` value possible. It is commonly represented as `BigDecimal` in some languages. - ```typespec scalar decimal ``` @@ -198,7 +204,6 @@ scalar decimal ### `decimal128` {#decimal128} A 128-bit decimal number. - ```typespec scalar decimal128 ``` @@ -208,7 +213,6 @@ scalar decimal128 ### `duration` {#duration} A duration/time period. e.g 5s, 10h - ```typespec scalar duration ``` @@ -218,7 +222,6 @@ scalar duration ### `float` {#float} A number with decimal value - ```typespec scalar float ``` @@ -228,7 +231,6 @@ scalar float ### `float32` {#float32} A 32 bit floating point number. (`±5.0 × 10^−324` to `±1.7 × 10^308`) - ```typespec scalar float32 ``` @@ -238,7 +240,6 @@ scalar float32 ### `float64` {#float64} A 32 bit floating point number. (`±1.5 x 10^−45` to `±3.4 x 10^38`) - ```typespec scalar float64 ``` @@ -248,7 +249,6 @@ scalar float64 ### `int16` {#int16} A 16-bit integer. (`-32,768` to `32,767`) - ```typespec scalar int16 ``` @@ -258,7 +258,6 @@ scalar int16 ### `int32` {#int32} A 32-bit integer. (`-2,147,483,648` to `2,147,483,647`) - ```typespec scalar int32 ``` @@ -268,7 +267,6 @@ scalar int32 ### `int64` {#int64} A 64-bit integer. (`-9,223,372,036,854,775,808` to `9,223,372,036,854,775,807`) - ```typespec scalar int64 ``` @@ -278,7 +276,6 @@ scalar int64 ### `int8` {#int8} A 8-bit integer. (`-128` to `127`) - ```typespec scalar int8 ``` @@ -289,7 +286,6 @@ scalar int8 A whole number. This represent any `integer` value possible. It is commonly represented as `BigInteger` in some languages. - ```typespec scalar integer ``` @@ -299,7 +295,6 @@ scalar integer ### `numeric` {#numeric} A numeric type - ```typespec scalar numeric ``` @@ -309,7 +304,6 @@ scalar numeric ### `offsetDateTime` {#offsetDateTime} A date and time in a particular time zone, e.g. "April 10th at 3:00am in PST" - ```typespec scalar offsetDateTime ``` @@ -319,7 +313,6 @@ scalar offsetDateTime ### `plainDate` {#plainDate} A date on a calendar without a time zone, e.g. "April 10th" - ```typespec scalar plainDate ``` @@ -329,7 +322,6 @@ scalar plainDate ### `plainTime` {#plainTime} A time on a clock without a time zone, e.g. "3:00 am" - ```typespec scalar plainTime ``` @@ -339,7 +331,6 @@ scalar plainTime ### `safeint` {#safeint} An integer that can be serialized to JSON (`−9007199254740991 (−(2^53 − 1))` to `9007199254740991 (2^53 − 1)` ) - ```typespec scalar safeint ``` @@ -349,7 +340,6 @@ scalar safeint ### `string` {#string} A sequence of textual characters. - ```typespec scalar string ``` @@ -359,7 +349,6 @@ scalar string ### `uint16` {#uint16} A 16-bit unsigned integer (`0` to `65,535`) - ```typespec scalar uint16 ``` @@ -369,7 +358,6 @@ scalar uint16 ### `uint32` {#uint32} A 32-bit unsigned integer (`0` to `4,294,967,295`) - ```typespec scalar uint32 ``` @@ -379,7 +367,6 @@ scalar uint32 ### `uint64` {#uint64} A 64-bit unsigned integer (`0` to `18,446,744,073,709,551,615`) - ```typespec scalar uint64 ``` @@ -389,7 +376,6 @@ scalar uint64 ### `uint8` {#uint8} A 8-bit unsigned integer (`0` to `255`) - ```typespec scalar uint8 ``` @@ -400,7 +386,6 @@ scalar uint8 Represent a 32-bit unix timestamp datetime with 1s of granularity. It measures time by the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970. - ```typespec scalar unixTimestamp32 ``` @@ -410,7 +395,6 @@ scalar unixTimestamp32 ### `url` {#url} Represent a URL string as described by https://url.spec.whatwg.org/ - ```typespec scalar url ``` @@ -420,7 +404,6 @@ scalar url ### `utcDateTime` {#utcDateTime} An instant in coordinated universal time (UTC)" - ```typespec scalar utcDateTime ``` diff --git a/docs/standard-library/built-in-decorators.md b/docs/standard-library/built-in-decorators.md index 58abd9aea7..fe3cf11a22 100644 --- a/docs/standard-library/built-in-decorators.md +++ b/docs/standard-library/built-in-decorators.md @@ -10,19 +10,18 @@ toc_max_heading_level: 3 Mark this type as deprecated. NOTE: This decorator **should not** be used, use the `#deprecated` directive instead. - ```typespec @deprecated(message: valueof string) ``` #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | |------|------|-------------| -| message | `valueof scalar string` | Deprecation message. | +| message | `valueof string` | Deprecation message. | #### Examples @@ -37,19 +36,18 @@ op Action(): Result; ### `@discriminator` {#@discriminator} Specify the property to be used to discriminate this type. - ```typespec @discriminator(propertyName: valueof string) ``` #### Target -`union Model | Union` +`Model | Union` #### Parameters | Name | Type | Description | |------|------|-------------| -| propertyName | `valueof scalar string` | The property name to use for discrimination | +| propertyName | `valueof string` | The property name to use for discrimination | #### Examples @@ -73,20 +71,19 @@ model Dog extends Pet {kind: "dog", bark: boolean} ### `@doc` {#@doc} Attach a documentation string. - ```typespec @doc(doc: valueof string, formatArgs?: {}) ``` #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | |------|------|-------------| -| doc | `valueof scalar string` | Documentation string | -| formatArgs | `model {}` | Record with key value pair that can be interpolated in the doc. | +| doc | `valueof string` | Documentation string | +| formatArgs | `{}` | Record with key value pair that can be interpolated in the doc. | #### Examples @@ -99,19 +96,18 @@ model Pet {} ### `@encode` {#@encode} Specify how to encode the target type. - ```typespec @encode(encoding: string | EnumMember, encodedAs?: Scalar) ``` #### Target -`union Scalar | ModelProperty` +`Scalar | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| encoding | `union string \| EnumMember` | Known name of an encoding. | +| encoding | `string \| EnumMember` | Known name of an encoding. | | encodedAs | `Scalar` | What target type is this being encoded as. Default to string. | #### Examples @@ -135,20 +131,19 @@ scalar myDateTime extends unixTimestamp; ### `@encodedName` {#@encodedName} Provide an alternative name for this type when serialized to the given mime type. - ```typespec @encodedName(mimeType: valueof string, name: valueof string) ``` #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | |------|------|-------------| -| mimeType | `valueof scalar string` | Mime type this should apply to. The mime type should be a known mime type as described here https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types without any suffix (e.g. `+json`) | -| name | `valueof scalar string` | Alternative name | +| mimeType | `valueof string` | Mime type this should apply to. The mime type should be a known mime type as described here https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types without any suffix (e.g. `+json`) | +| name | `valueof string` | Alternative name | #### Examples @@ -172,7 +167,6 @@ expireAt: int32; ### `@error` {#@error} Specify that this model is an error type. Operations return error types when the operation has failed. - ```typespec @error ``` @@ -199,7 +193,6 @@ message: string; Attach a documentation string to describe the error return types of an operation. If an operation returns a union of success and errors it only describe the errors. See `@errorsDoc` for success documentation. - ```typespec @errorsDoc(doc: valueof string) ``` @@ -211,7 +204,7 @@ If an operation returns a union of success and errors it only describe the error #### Parameters | Name | Type | Description | |------|------|-------------| -| doc | `valueof scalar string` | Documentation string | +| doc | `valueof string` | Documentation string | #### Examples @@ -226,19 +219,18 @@ op get(): Pet | NotFound; Specify a known data format hint for this string type. For example `uuid`, `uri`, etc. This differs from the `@pattern` decorator which is meant to specify a regular expression while `@format` accepts a known format name. The format names are open ended and are left to emitter to interpret. - ```typespec @format(format: valueof string) ``` #### Target -`union string | bytes | ModelProperty` +`string | bytes | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| format | `valueof scalar string` | format name. | +| format | `valueof string` | format name. | #### Examples @@ -251,20 +243,19 @@ scalar uuid extends string; ### `@friendlyName` {#@friendlyName} Specifies how a templated type should name their instances. - ```typespec @friendlyName(name: valueof string, formatArgs?: unknown) ``` #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | |------|------|-------------| -| name | `valueof scalar string` | name the template instance should take | -| formatArgs | `(intrinsic) unknown` | Model with key value used to interpolate the name | +| name | `valueof string` | name the template instance should take | +| formatArgs | `unknown` | Model with key value used to interpolate the name | #### Examples @@ -280,45 +271,42 @@ nextLink: string; ### `@inspectType` {#@inspectType} A debugging decorator used to inspect a type. - ```typespec @inspectType(text: valueof string) ``` #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | |------|------|-------------| -| text | `valueof scalar string` | Custom text to log | +| text | `valueof string` | Custom text to log | ### `@inspectTypeName` {#@inspectTypeName} A debugging decorator used to inspect a type name. - ```typespec @inspectTypeName(text: valueof string) ``` #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | |------|------|-------------| -| text | `valueof scalar string` | Custom text to log | +| text | `valueof string` | Custom text to log | ### `@key` {#@key} Mark a model property as the key to identify instances of that type - ```typespec @key(altName?: valueof string) ``` @@ -330,7 +318,7 @@ Mark a model property as the key to identify instances of that type #### Parameters | Name | Type | Description | |------|------|-------------| -| altName | `valueof scalar string` | Name of the property. If not specified, the decorated property name is used. | +| altName | `valueof string` | Name of the property. If not specified, the decorated property name is used. | #### Examples @@ -344,14 +332,13 @@ model Pet { ### `@knownValues` {#@knownValues} Provide a set of known values to a string type. - ```typespec @knownValues(values: Enum) ``` #### Target -`union string | numeric | ModelProperty` +`string | numeric | ModelProperty` #### Parameters | Name | Type | Description | @@ -374,7 +361,6 @@ Invalid, ### `@list` {#@list} Mark this operation as a `list` operation for resource types. - ```typespec @list(listedType?: Model) ``` @@ -393,19 +379,18 @@ Mark this operation as a `list` operation for resource types. ### `@maxItems` {#@maxItems} Specify the maximum number of items this array should have. - ```typespec @maxItems(value: valueof integer) ``` #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar integer` | Maximum number | +| value | `valueof integer` | Maximum number | #### Examples @@ -418,19 +403,18 @@ model Endpoints is string[]; ### `@maxLength` {#@maxLength} Specify the maximum length this string type should be. - ```typespec @maxLength(value: valueof integer) ``` #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar integer` | Maximum length | +| value | `valueof integer` | Maximum length | #### Examples @@ -443,19 +427,18 @@ scalar Username extends string; ### `@maxValue` {#@maxValue} Specify the maximum value this numeric type should be. - ```typespec @maxValue(value: valueof numeric) ``` #### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar numeric` | Maximum value | +| value | `valueof numeric` | Maximum value | #### Examples @@ -469,19 +452,18 @@ scalar Age is int32; Specify the maximum value this numeric type should be, exclusive of the given value. - ```typespec @maxValueExclusive(value: valueof numeric) ``` #### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar numeric` | Maximum value | +| value | `valueof numeric` | Maximum value | #### Examples @@ -494,19 +476,18 @@ scalar distance is float64; ### `@minItems` {#@minItems} Specify the minimum number of items this array should have. - ```typespec @minItems(value: valueof integer) ``` #### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar integer` | Minimum number | +| value | `valueof integer` | Minimum number | #### Examples @@ -519,19 +500,18 @@ model Endpoints is string[]; ### `@minLength` {#@minLength} Specify the minimum length this string type should be. - ```typespec @minLength(value: valueof integer) ``` #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar integer` | Minimum length | +| value | `valueof integer` | Minimum length | #### Examples @@ -544,19 +524,18 @@ scalar Username extends string; ### `@minValue` {#@minValue} Specify the minimum value this numeric type should be. - ```typespec @minValue(value: valueof numeric) ``` #### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar numeric` | Minimum value | +| value | `valueof numeric` | Minimum value | #### Examples @@ -570,19 +549,18 @@ scalar Age is int32; Specify the minimum value this numeric type should be, exclusive of the given value. - ```typespec @minValueExclusive(value: valueof numeric) ``` #### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| value | `valueof scalar numeric` | Minimum value | +| value | `valueof numeric` | Minimum value | #### Examples @@ -595,7 +573,6 @@ scalar distance is float64; ### `@overload` {#@overload} Specify this operation is an overload of the given operation. - ```typespec @overload(overloadbase: Operation) ``` @@ -623,7 +600,6 @@ op uploadBytes(data: bytes, @header contentType: "application/octet-stream"): vo ### `@parameterVisibility` {#@parameterVisibility} Sets which visibilities apply to parameters for the given operation. - ```typespec @parameterVisibility(...visibilities: valueof string[]) ``` @@ -635,7 +611,7 @@ Sets which visibilities apply to parameters for the given operation. #### Parameters | Name | Type | Description | |------|------|-------------| -| visibilities | `valueof model string[]` | List of visibility strings which apply to this operation. | +| visibilities | `valueof string[]` | List of visibility strings which apply to this operation. | @@ -649,20 +625,19 @@ This decorator may optionally provide a custom validation _message_. Emitters ma context when pattern validation fails. For the sake of consistency, the message should be a phrase that describes in plain language what sort of content the pattern attempts to validate. For example, a complex regular expression that validates a GUID string might have a message like "Must be a valid GUID." - ```typespec @pattern(pattern: valueof string, validationMessage?: valueof string) ``` #### Target -`union string | bytes | ModelProperty` +`string | bytes | ModelProperty` #### Parameters | Name | Type | Description | |------|------|-------------| -| pattern | `valueof scalar string` | Regular expression. | -| validationMessage | `valueof scalar string` | Optional validation message that may provide context when validation fails. | +| pattern | `valueof string` | Regular expression. | +| validationMessage | `valueof string` | Optional validation message that may provide context when validation fails. | #### Examples @@ -677,20 +652,19 @@ scalar LowerAlpha extends string; DEPRECATED: Use `@encodedName` instead. Provide an alternative name for this type. - ```typespec @projectedName(targetName: valueof string, projectedName: valueof string) ``` #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | |------|------|-------------| -| targetName | `valueof scalar string` | Projection target | -| projectedName | `valueof scalar string` | Alternative name | +| targetName | `valueof string` | Projection target | +| projectedName | `valueof string` | Alternative name | #### Examples @@ -706,7 +680,6 @@ expireAt: int32; Attach a documentation string to describe the successful return types of an operation. If an operation returns a union of success and errors it only describe the success. See `@errorsDoc` for error documentation. - ```typespec @returnsDoc(doc: valueof string) ``` @@ -718,7 +691,7 @@ If an operation returns a union of success and errors it only describe the succe #### Parameters | Name | Type | Description | |------|------|-------------| -| doc | `valueof scalar string` | Documentation string | +| doc | `valueof string` | Documentation string | #### Examples @@ -731,7 +704,6 @@ op get(): Pet | NotFound; ### `@returnTypeVisibility` {#@returnTypeVisibility} Sets which visibilities apply to the return type for the given operation. - ```typespec @returnTypeVisibility(...visibilities: valueof string[]) ``` @@ -743,21 +715,20 @@ Sets which visibilities apply to the return type for the given operation. #### Parameters | Name | Type | Description | |------|------|-------------| -| visibilities | `valueof model string[]` | List of visibility strings which apply to this operation. | +| visibilities | `valueof string[]` | List of visibility strings which apply to this operation. | ### `@secret` {#@secret} Mark this string as a secret value that should be treated carefully to avoid exposure - ```typespec @secret ``` #### Target -`union string | ModelProperty` +`string | ModelProperty` #### Parameters None @@ -773,7 +744,6 @@ scalar Password is string; ### `@service` {#@service} Mark this namespace as describing a service and configure service properties. - ```typespec @service(options?: ServiceOptions) ``` @@ -785,7 +755,7 @@ Mark this namespace as describing a service and configure service properties. #### Parameters | Name | Type | Description | |------|------|-------------| -| options | `model ServiceOptions` | Optional configuration for the service. | +| options | [`ServiceOptions`](./built-in-data-types.md#ServiceOptions) | Optional configuration for the service. | #### Examples @@ -812,19 +782,18 @@ namespace PetStore; ### `@summary` {#@summary} Typically a short, single-line description. - ```typespec @summary(summary: valueof string) ``` #### Target -`(intrinsic) unknown` +`unknown` #### Parameters | Name | Type | Description | |------|------|-------------| -| summary | `valueof scalar string` | Summary string. | +| summary | `valueof string` | Summary string. | #### Examples @@ -837,19 +806,18 @@ model Pet {} ### `@tag` {#@tag} Attaches a tag to an operation, interface, or namespace. Multiple `@tag` decorators can be specified to attach multiple tags to a TypeSpec element. - ```typespec @tag(tag: valueof string) ``` #### Target -`union Namespace | Interface | Operation` +`Namespace | Interface | Operation` #### Parameters | Name | Type | Description | |------|------|-------------| -| tag | `valueof scalar string` | Tag value | +| tag | `valueof string` | Tag value | @@ -870,7 +838,6 @@ with standard emitters that interpret them as follows: - "delete": input to operations that delete data. See also: [Automatic visibility](https://typespec.io/docs/libraries/http/operations#automatic-visibility) - ```typespec @visibility(...visibilities: valueof string[]) ``` @@ -882,7 +849,7 @@ See also: [Automatic visibility](https://typespec.io/docs/libraries/http/operati #### Parameters | Name | Type | Description | |------|------|-------------| -| visibilities | `valueof model string[]` | List of visibilities which apply to this property. | +| visibilities | `valueof string[]` | List of visibilities which apply to this property. | #### Examples @@ -901,7 +868,6 @@ name: string; ### `@withDefaultKeyVisibility` {#@withDefaultKeyVisibility} Set the visibility of key properties in a model if not already set. - ```typespec @withDefaultKeyVisibility(visibility: valueof string) ``` @@ -913,14 +879,13 @@ Set the visibility of key properties in a model if not already set. #### Parameters | Name | Type | Description | |------|------|-------------| -| visibility | `valueof scalar string` | The desired default visibility value. If a key property already has a `visibility` decorator then the default visibility is not applied. | +| visibility | `valueof string` | The desired default visibility value. If a key property already has a `visibility` decorator then the default visibility is not applied. | ### `@withOptionalProperties` {#@withOptionalProperties} Returns the model with required properties removed. - ```typespec @withOptionalProperties ``` @@ -937,7 +902,6 @@ None ### `@withoutDefaultValues` {#@withoutDefaultValues} Returns the model with any default values removed. - ```typespec @withoutDefaultValues ``` @@ -954,7 +918,6 @@ None ### `@withoutOmittedProperties` {#@withoutOmittedProperties} Returns the model with the given properties omitted. - ```typespec @withoutOmittedProperties(omit: string | Union) ``` @@ -966,14 +929,13 @@ Returns the model with the given properties omitted. #### Parameters | Name | Type | Description | |------|------|-------------| -| omit | `union string \| Union` | List of properties to omit | +| omit | `string \| Union` | List of properties to omit | ### `@withUpdateableProperties` {#@withUpdateableProperties} Returns the model with non-updateable properties removed. - ```typespec @withUpdateableProperties ``` @@ -998,7 +960,6 @@ See also: [Automatic visibility](https://typespec.io/docs/libraries/http/operati When using an emitter that applies visibility automatically, it is generally not necessary to use this decorator. - ```typespec @withVisibility(...visibilities: valueof string[]) ``` @@ -1010,7 +971,7 @@ not necessary to use this decorator. #### Parameters | Name | Type | Description | |------|------|-------------| -| visibilities | `valueof model string[]` | List of visibilities which apply to this property. | +| visibilities | `valueof string[]` | List of visibilities which apply to this property. | #### Examples diff --git a/packages/compiler/src/config/config-to-options.ts b/packages/compiler/src/config/config-to-options.ts index ee43969dfb..d6778d0ca2 100644 --- a/packages/compiler/src/config/config-to-options.ts +++ b/packages/compiler/src/config/config-to-options.ts @@ -37,7 +37,7 @@ export interface ConfigToOptionsOptions { /** * Resolve the compiler options for the given entrypoint by resolving the tspconfig.yaml. * @param host Compiler host - * @param compilerOptions + * @param options */ export async function resolveCompilerOptions( host: CompilerHost, diff --git a/packages/compiler/src/core/decorator-utils.ts b/packages/compiler/src/core/decorator-utils.ts index 206255d72b..513da7ec03 100644 --- a/packages/compiler/src/core/decorator-utils.ts +++ b/packages/compiler/src/core/decorator-utils.ts @@ -36,10 +36,10 @@ export type InferredTypeSpecValue = /** * Validate the decorator target is matching the expected value. - * @param program + * @param context * @param target - * @param expectedType * @param decoratorName + * @param expectedType * @returns */ export function validateDecoratorTarget( diff --git a/packages/compiler/src/core/diagnostics.ts b/packages/compiler/src/core/diagnostics.ts index f7067e1bdb..feb4b484a5 100644 --- a/packages/compiler/src/core/diagnostics.ts +++ b/packages/compiler/src/core/diagnostics.ts @@ -294,7 +294,7 @@ export function createDiagnosticCollector(): DiagnosticCollector { /** * Ignore the diagnostics emitted by the diagnostic accessor pattern and just return the actual result. - * @param result: Accessor pattern tuple result including the actual result and the list of diagnostics. + * @param result Accessor pattern tuple result including the actual result and the list of diagnostics. * @returns Actual result. */ export function ignoreDiagnostics(result: DiagnosticResult): T { diff --git a/packages/compiler/src/core/helpers/type-name-utils.ts b/packages/compiler/src/core/helpers/type-name-utils.ts index 32ea713ed9..8bbdd1e8df 100644 --- a/packages/compiler/src/core/helpers/type-name-utils.ts +++ b/packages/compiler/src/core/helpers/type-name-utils.ts @@ -48,6 +48,7 @@ export function getTypeName(type: Type | ValueType, options?: TypeNameOptions): case "StringTemplate": return "string"; case "String": + return `"${type.value}"`; case "Number": case "Boolean": return type.value.toString(); diff --git a/packages/compiler/src/core/types.ts b/packages/compiler/src/core/types.ts index 544a9057b1..48463c7758 100644 --- a/packages/compiler/src/core/types.ts +++ b/packages/compiler/src/core/types.ts @@ -1916,7 +1916,7 @@ export interface CompilerHost { * @param path Path to the directory. * @returns list of file/directory in the given directory. Returns the name not the full path. */ - readDir(dir: string): Promise; + readDir(path: string): Promise; /** * Deletes a directory or file. @@ -2317,7 +2317,7 @@ export interface Tracer { trace(area: string, message: string, target?: DiagnosticTarget): void; /** - * @param area + * @param subarea */ sub(subarea: string): Tracer; } diff --git a/packages/compiler/test/checker/model.test.ts b/packages/compiler/test/checker/model.test.ts index 5f3ed2e633..81ce85ac5e 100644 --- a/packages/compiler/test/checker/model.test.ts +++ b/packages/compiler/test/checker/model.test.ts @@ -129,10 +129,10 @@ describe("compiler: models", () => { describe("doesn't allow a default of different type than the property type", () => { const testCases: [string, string, string][] = [ ["string", "123", "Type '123' is not assignable to type 'string'"], - ["int32", `"foo"`, "Type 'foo' is not assignable to type 'int32'"], - ["boolean", `"foo"`, "Type 'foo' is not assignable to type 'boolean'"], + ["int32", `"foo"`, `Type '"foo"' is not assignable to type 'int32'`], + ["boolean", `"foo"`, `Type '"foo"' is not assignable to type 'boolean'`], ["string[]", `["foo", 123]`, `Type '123' is not assignable to type 'string'`], - [`"foo" | "bar"`, `"foo1"`, "Type 'foo1' is not assignable to type 'foo | bar'"], + [`"foo" | "bar"`, `"foo1"`, `Type '"foo1"' is not assignable to type '"foo" | "bar"'`], ]; for (const [type, defaultValue, errorMessage] of testCases) { diff --git a/packages/compiler/test/checker/relation.test.ts b/packages/compiler/test/checker/relation.test.ts index 308d2cd5a7..91ece1a3d0 100644 --- a/packages/compiler/test/checker/relation.test.ts +++ b/packages/compiler/test/checker/relation.test.ts @@ -239,7 +239,7 @@ describe("compiler: checker: type relations", () => { { source: `"bar"`, target: `"foo"` }, { code: "unassignable", - message: "Type 'bar' is not assignable to type 'foo'", + message: `Type '"bar"' is not assignable to type '"foo"'`, } ); }); @@ -249,7 +249,7 @@ describe("compiler: checker: type relations", () => { { source: `string`, target: `"foo"` }, { code: "unassignable", - message: "Type 'string' is not assignable to type 'foo'", + message: `Type 'string' is not assignable to type '"foo"'`, } ); }); @@ -1102,7 +1102,7 @@ describe("compiler: checker: type relations", () => { { source: `"foo bar"`, target: "valueof int16" }, { code: "unassignable", - message: "Type 'foo bar' is not assignable to type 'int16'", + message: `Type '"foo bar"' is not assignable to type 'int16'`, } ); }); @@ -1128,7 +1128,7 @@ describe("compiler: checker: type relations", () => { { source: `"foo bar"`, target: "valueof float32" }, { code: "unassignable", - message: "Type 'foo bar' is not assignable to type 'float32'", + message: `Type '"foo bar"' is not assignable to type 'float32'`, } ); }); diff --git a/packages/compiler/test/checker/templates.test.ts b/packages/compiler/test/checker/templates.test.ts index 4538a72c53..1b5ffc97d7 100644 --- a/packages/compiler/test/checker/templates.test.ts +++ b/packages/compiler/test/checker/templates.test.ts @@ -280,7 +280,7 @@ describe("compiler: templates", () => { // Only one error, Bar can't be created as T is not constraint to object expectDiagnostics(diagnostics, { code: "unassignable", - message: "Type 'abc' is not assignable to type '{}'", + message: `Type '"abc"' is not assignable to type '{}'`, pos, }); }); diff --git a/packages/compiler/test/decorators/decorators.test.ts b/packages/compiler/test/decorators/decorators.test.ts index 8cb9d89ac9..e889a767e4 100644 --- a/packages/compiler/test/decorators/decorators.test.ts +++ b/packages/compiler/test/decorators/decorators.test.ts @@ -668,7 +668,7 @@ describe("compiler: built-in decorators", () => { '"int32"', // TODO: Arguably this should be improved. "invalid-argument", - `Argument 'int32' is not assignable to parameter of type 'Scalar'`, + `Argument '"int32"' is not assignable to parameter of type 'Scalar'`, ], ]; describe("valid", () => { @@ -794,7 +794,7 @@ describe("compiler: built-in decorators", () => { expectDiagnostics(diagnostics, { code: "invalid-argument", - message: "Argument 'foo' is not assignable to parameter of type 'Operation'", + message: `Argument '"foo"' is not assignable to parameter of type 'Operation'`, severity: "error", }); }); diff --git a/packages/http/README.md b/packages/http/README.md index 099ef915ba..8af39b6941 100644 --- a/packages/http/README.md +++ b/packages/http/README.md @@ -158,9 +158,9 @@ Specify this property is to be sent or received as an HTTP header. ##### Parameters -| Name | Type | Description | -| ------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| headerNameOrOptions | `union string \| TypeSpec.Http.HeaderOptions` | Optional name of the header when sent over HTTP or header options.
By default the header name will be the property name converted from camelCase to kebab-case. (e.g. `contentType` -> `content-type`) | +| Name | Type | Description | +| ------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| headerNameOrOptions | `string \| TypeSpec.Http.HeaderOptions` | Optional name of the header when sent over HTTP or header options.
By default the header name will be the property name converted from camelCase to kebab-case. (e.g. `contentType` -> `content-type`) | ##### Examples @@ -196,13 +196,13 @@ Specify if inapplicable metadata should be included in the payload for the given ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters -| Name | Type | Description | -| ----- | ------------------------ | --------------------------------------------------------------- | -| value | `valueof scalar boolean` | If true, inapplicable metadata will be included in the payload. | +| Name | Type | Description | +| ----- | ----------------- | --------------------------------------------------------------- | +| value | `valueof boolean` | If true, inapplicable metadata will be included in the payload. | #### `@patch` @@ -240,9 +240,9 @@ Explicitly specify that this property is to be interpolated as a path parameter. ##### Parameters -| Name | Type | Description | -| --------- | ----------------------- | --------------------------------------------------- | -| paramName | `valueof scalar string` | Optional name of the parameter in the url template. | +| Name | Type | Description | +| --------- | ---------------- | --------------------------------------------------- | +| paramName | `valueof string` | Optional name of the parameter in the url template. | ##### Examples @@ -309,9 +309,9 @@ Specify this property is to be sent as a query parameter. ##### Parameters -| Name | Type | Description | -| ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------- | -| queryNameOrOptions | `union string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. | +| Name | Type | Description | +| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------- | +| queryNameOrOptions | `string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. | ##### Examples @@ -342,14 +342,14 @@ it will be used as a prefix to the route URI of the operation. ##### Target -`union Namespace | Interface | Operation` +`Namespace | Interface | Operation` ##### Parameters -| Name | Type | Description | -| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| path | `valueof scalar string` | Relative route path. Cannot include query parameters. | -| options | `model (anonymous model)` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | +| Name | Type | Description | +| ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| path | `valueof string` | Relative route path. Cannot include query parameters. | +| options | `{...}` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. | ##### Examples @@ -372,11 +372,11 @@ Specify the endpoint for this service. ##### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ------------------------------------------------------- | -| url | `valueof scalar string` | Server endpoint | -| description | `valueof scalar string` | Description of the endpoint | -| parameters | `model Record` | Optional set of parameters used to interpolate the url. | +| Name | Type | Description | +| ----------- | ----------------- | ------------------------------------------------------- | +| url | `valueof string` | Server endpoint | +| description | `valueof string` | Description of the endpoint | +| parameters | `Record` | Optional set of parameters used to interpolate the url. | ##### Examples @@ -455,13 +455,13 @@ Specify authentication for a whole service or specific methods. See the [documen ##### Target -`union Namespace | Interface | Operation` +`Namespace | Interface | Operation` ##### Parameters -| Name | Type | Description | -| ---- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| auth | `union {} \| Union \| {}[]` | Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple (must use all authentication together) | +| Name | Type | Description | +| ---- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| auth | `{} \| Union \| {}[]` | Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple (must use all authentication together) | ##### Examples diff --git a/packages/http/test/http-decorators.test.ts b/packages/http/test/http-decorators.test.ts index c95a696c31..ab292519c7 100644 --- a/packages/http/test/http-decorators.test.ts +++ b/packages/http/test/http-decorators.test.ts @@ -667,8 +667,7 @@ describe("http: decorators", () => { expectDiagnostics(diagnostics, [ { code: "unassignable", - message: - "Type 'foo' is not assignable to type 'TypeSpec.Http.AuthorizationCodeFlow | TypeSpec.Http.ImplicitFlow | TypeSpec.Http.PasswordFlow | TypeSpec.Http.ClientCredentialsFlow'", + message: `Type '"foo"' is not assignable to type 'TypeSpec.Http.AuthorizationCodeFlow | TypeSpec.Http.ImplicitFlow | TypeSpec.Http.PasswordFlow | TypeSpec.Http.ClientCredentialsFlow'`, }, { code: "unassignable", diff --git a/packages/json-schema/README.md b/packages/json-schema/README.md index 562a597035..9abdc9d89e 100644 --- a/packages/json-schema/README.md +++ b/packages/json-schema/README.md @@ -112,9 +112,9 @@ Set the base URI for any schemas emitted from types within this namespace. ##### Parameters -| Name | Type | Description | -| ------- | ----------------------- | ------------------------------------------------------------------------ | -| baseUri | `valueof scalar string` | the base URI. Schema IDs inside this namespace are relative to this URI. | +| Name | Type | Description | +| ------- | ---------------- | ------------------------------------------------------------------------ | +| baseUri | `valueof string` | the base URI. Schema IDs inside this namespace are relative to this URI. | #### `@contains` @@ -127,13 +127,13 @@ Use `@minContains` and `@maxContains` to customize how many instances to expect. ##### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | --------------------- | -------------------------------- | -| value | `(intrinsic) unknown` | The type the array must contain. | +| Name | Type | Description | +| ----- | --------- | -------------------------------- | +| value | `unknown` | The type the array must contain. | #### `@contentEncoding` @@ -145,13 +145,13 @@ Specify the encoding used for the contents of a string. ##### Target -`union string | ModelProperty` +`string | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ----------- | -| value | `valueof scalar string` |
| +| Name | Type | Description | +| ----- | ---------------- | ----------- | +| value | `valueof string` |
| #### `@contentMediaType` @@ -163,13 +163,13 @@ Specify the content type of content stored in a string. ##### Target -`union string | ModelProperty` +`string | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ------------------------------------- | -| value | `valueof scalar string` | the media type of the string contents | +| Name | Type | Description | +| ----- | ---------------- | ------------------------------------- | +| value | `valueof string` | the media type of the string contents | #### `@contentSchema` @@ -182,13 +182,13 @@ media type and encoding. ##### Target -`union string | ModelProperty` +`string | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | --------------------- | --------------------------------- | -| value | `(intrinsic) unknown` | the schema of the string contents | +| Name | Type | Description | +| ----- | --------- | --------------------------------- | +| value | `unknown` | the schema of the string contents | #### `@extension` @@ -204,14 +204,14 @@ emit the raw JSON code `{x: "value"}`. ##### Target -`(intrinsic) unknown` +`unknown` ##### 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 string` | the name of the keyword of vendor extension, e.g. `x-custom`. | +| value | `unknown` | the value of the keyword. Will be converted to a schema unless wrapped in `Json`. | #### `@id` @@ -226,13 +226,13 @@ By default, the id will be constructed based on the declaration's name. ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ----------------------------------------------- | -| id | `valueof scalar string` | the id of the JSON schema for this declaration. | +| Name | Type | Description | +| ---- | ---------------- | ----------------------------------------------- | +| id | `valueof string` | the id of the JSON schema for this declaration. | #### `@jsonSchema` @@ -248,13 +248,13 @@ you can provide the id. ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters -| Name | Type | Description | -| ------- | ----------------------- | --------------------------------------------------- | -| baseUri | `valueof scalar string` | Schema IDs are interpreted as relative to this URI. | +| Name | Type | Description | +| ------- | ---------------- | --------------------------------------------------- | +| baseUri | `valueof string` | Schema IDs are interpreted as relative to this URI. | #### `@maxContains` @@ -267,13 +267,13 @@ by the contains decorator. ##### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The maximum number of instances the array must contain | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The maximum number of instances the array must contain | #### `@maxProperties` @@ -285,13 +285,13 @@ Specify the maximum number of properties this object can have. ##### Target -`union Record | ModelProperty` +`Record | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The maximum number of properties this object can have. | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The maximum number of properties this object can have. | #### `@minContains` @@ -304,13 +304,13 @@ by the contains decorator. ##### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The minimum number of instances the array must contain | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The minimum number of instances the array must contain | #### `@minProperties` @@ -322,13 +322,13 @@ Specify the minimum number of properties this object can have. ##### Target -`union Record | ModelProperty` +`Record | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ---------------------- | ------------------------------------------------------ | -| value | `valueof scalar int32` | The minimum number of properties this object can have. | +| Name | Type | Description | +| ----- | --------------- | ------------------------------------------------------ | +| value | `valueof int32` | The minimum number of properties this object can have. | #### `@multipleOf` @@ -340,13 +340,13 @@ Specify that the numeric type must be a multiple of some numeric value. ##### Target -`union numeric | ModelProperty` +`numeric | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ------------------------ | -------------------------------------------------- | -| value | `valueof scalar numeric` | The numeric type must be a multiple of this value. | +| Name | Type | Description | +| ----- | ----------------- | -------------------------------------------------- | +| value | `valueof numeric` | The numeric type must be a multiple of this value. | #### `@prefixItems` @@ -358,13 +358,13 @@ Specify that the target array must begin with the provided types. ##### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` ##### Parameters -| Name | Type | Description | -| ----- | ----------------- | --------------------------------------------------------------------------- | -| value | `model unknown[]` | a tuple containing the types that must be present at the start of the array | +| Name | Type | Description | +| ----- | ----------- | --------------------------------------------------------------------------- | +| value | `unknown[]` | a tuple containing the types that must be present at the start of the array | #### `@uniqueItems` @@ -376,7 +376,7 @@ Specify that every item in the array must be unique. ##### Target -`union unknown[] | ModelProperty` +`unknown[] | ModelProperty` ##### Parameters diff --git a/packages/openapi/README.md b/packages/openapi/README.md index 05e3b1e9e6..3e5a84e4b0 100644 --- a/packages/openapi/README.md +++ b/packages/openapi/README.md @@ -54,14 +54,14 @@ Attach some custom data to the OpenAPI element generated from this type. ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ----------------------------------- | -| key | `valueof scalar string` | Extension key. Must start with `x-` | -| value | `(intrinsic) unknown` | Extension value. | +| Name | Type | Description | +| ----- | ---------------- | ----------------------------------- | +| key | `valueof string` | Extension key. Must start with `x-` | +| value | `unknown` | Extension value. | ##### Examples @@ -86,14 +86,14 @@ Specify the OpenAPI `externalDocs` property for this type. ##### Target -`(intrinsic) unknown` +`unknown` ##### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ----------------------- | -| url | `valueof scalar string` | Url to the docs | -| description | `valueof scalar string` | Description of the docs | +| Name | Type | Description | +| ----------- | ---------------- | ----------------------- | +| url | `valueof string` | Url to the docs | +| description | `valueof string` | Description of the docs | ##### Examples @@ -120,9 +120,9 @@ The service `title` and `version` are already specified using `@service`. ##### Parameters -| Name | Type | Description | -| -------------- | --------------------------------------- | ---------------------- | -| additionalInfo | `model TypeSpec.OpenAPI.AdditionalInfo` | Additional information | +| Name | Type | Description | +| -------------- | ----------------------------------- | ---------------------- | +| additionalInfo | [`AdditionalInfo`](#additionalinfo) | Additional information | #### `@operationId` @@ -138,9 +138,9 @@ Specify the OpenAPI `operationId` property for this operation. ##### Parameters -| Name | Type | Description | -| ----------- | ----------------------- | ------------------- | -| operationId | `valueof scalar string` | Operation id value. | +| Name | Type | Description | +| ----------- | ---------------- | ------------------- | +| operationId | `valueof string` | Operation id value. | ##### Examples diff --git a/packages/openapi/src/decorators.ts b/packages/openapi/src/decorators.ts index 58869af2c2..886a6e0f50 100644 --- a/packages/openapi/src/decorators.ts +++ b/packages/openapi/src/decorators.ts @@ -110,7 +110,7 @@ const externalDocsKey = createStateSymbol("externalDocs"); /** * Allows referencing an external resource for extended documentation. * @param url The URL for the target documentation. Value MUST be in the format of a URL. - * @param @optional description A short description of the target documentation. + * @param description A short description of the target documentation. */ export function $externalDocs( context: DecoratorContext, diff --git a/packages/openapi3/README.md b/packages/openapi3/README.md index 0648f87a67..a41e857f9b 100644 --- a/packages/openapi3/README.md +++ b/packages/openapi3/README.md @@ -103,7 +103,7 @@ Specify that `oneOf` should be used instead of `anyOf` for that union. ##### Target -`union Union | ModelProperty` +`Union | ModelProperty` ##### Parameters @@ -119,10 +119,10 @@ Specify an external reference that should be used inside of emitting this type. ##### Target -`union Model | ModelProperty` +`Model | ModelProperty` ##### Parameters -| Name | Type | Description | -| ---- | ----------------------- | -------------------------------------------------------------------- | -| ref | `valueof scalar string` | External reference(e.g. "../../common.json#/components/schemas/Foo") | +| Name | Type | Description | +| ---- | ---------------- | -------------------------------------------------------------------- | +| ref | `valueof string` | External reference(e.g. "../../common.json#/components/schemas/Foo") | diff --git a/packages/protobuf/README.md b/packages/protobuf/README.md index 15d2af2b6b..5e364aadb7 100644 --- a/packages/protobuf/README.md +++ b/packages/protobuf/README.md @@ -71,9 +71,9 @@ The field index of a Protobuf message must: ##### Parameters -| Name | Type | Description | -| ----- | ----------------------- | ------------------------------------ | -| index | `valueof scalar uint32` | The whole-number index of the field. | +| Name | Type | Description | +| ----- | ---------------- | ------------------------------------ | +| index | `valueof uint32` | The whole-number index of the field. | ##### Examples @@ -101,7 +101,7 @@ This decorator will force the emitter to check and emit a model. ##### Target -`model {}` +`{}` ##### Parameters @@ -122,9 +122,9 @@ single Protobuf file. ##### Parameters -| Name | Type | Description | -| ------- | ---------------------------------------- | ----------------------------------- | -| details | `model TypeSpec.Protobuf.PackageDetails` | the optional details of the package | +| Name | Type | Description | +| ------- | ----------------------------------- | ----------------------------------- | +| details | [`PackageDetails`](#packagedetails) | the optional details of the package | #### `@reserve` @@ -155,13 +155,13 @@ information. ##### Target -`model {}` +`{}` ##### Parameters -| Name | Type | Description | -| ------------ | ------------------------------------------------------ | ---------------------------- | -| reservations | `valueof model string \| [uint32, uint32] \| uint32[]` | a list of field reservations | +| Name | Type | Description | +| ------------ | ------------------------------------------------ | ---------------------------- | +| reservations | `valueof string \| [uint32, uint32] \| uint32[]` | a list of field reservations | ##### Examples @@ -204,9 +204,9 @@ Set the streaming mode of an operation. See [StreamMode](./data-types#TypeSpec.P ##### Parameters -| Name | Type | Description | -| ---- | ----------------------------------- | ---------------------------------------------- | -| mode | `enum TypeSpec.Protobuf.StreamMode` | The streaming mode to apply to this operation. | +| Name | Type | Description | +| ---- | --------------------------- | ---------------------------------------------- | +| mode | [`StreamMode`](#streammode) | The streaming mode to apply to this operation. | ##### Examples diff --git a/packages/rest/README.md b/packages/rest/README.md index 460db1aee1..6b7744b780 100644 --- a/packages/rest/README.md +++ b/packages/rest/README.md @@ -43,27 +43,27 @@ Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my ##### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ----------------------------------------------------------------------------- | -| name | `valueof scalar string` | Name of the action. If not specified, the name of the operation will be used. | +| Name | Type | Description | +| ---- | ---------------- | ----------------------------------------------------------------------------- | +| name | `valueof string` | Name of the action. If not specified, the name of the operation will be used. | #### `@actionSeparator` Defines the separator string that is inserted before the action name in auto-generated routes for actions. ```typespec -@TypeSpec.Rest.actionSeparator(seperator: valueof / | : | /:) +@TypeSpec.Rest.actionSeparator(seperator: valueof "/" | ":" | "/:") ``` ##### Target -`union Model | ModelProperty | Operation` +`Model | ModelProperty | Operation` ##### Parameters | Name | Type | Description | | --------- | ---------------------------- | ---------------------------------------------------------------- | -| seperator | `valueof union / \| : \| /:` | Seperator seperating the action segment from the rest of the url | +| seperator | `valueof "/" \| ":" \| "/:"` | Seperator seperating the action segment from the rest of the url | #### `@autoRoute` @@ -75,7 +75,7 @@ This interface or operation should resolve its route automatically. To be used w ##### Target -`union Interface | Operation` +`Interface | Operation` ##### Parameters @@ -104,10 +104,10 @@ Specify this operation is a collection action. (Scopped to a resource, /pets/my- ##### Parameters -| Name | Type | Description | -| ------------ | ----------------------- | ----------------------------------------------------------------------------- | -| resourceType | `Model` | Resource marked with | -| name | `valueof scalar string` | Name of the action. If not specified, the name of the operation will be used. | +| Name | Type | Description | +| ------------ | ---------------- | ----------------------------------------------------------------------------- | +| resourceType | `Model` | Resource marked with | +| name | `valueof string` | Name of the action. If not specified, the name of the operation will be used. | #### `@copyResourceKeyParameters` @@ -123,9 +123,9 @@ Copy the resource key parameters on the model ##### Parameters -| Name | Type | Description | -| ------ | ----------------------- | ------------------------------------- | -| filter | `valueof scalar string` | Filter to exclude certain properties. | +| Name | Type | Description | +| ------ | ---------------- | ------------------------------------- | +| filter | `valueof string` | Filter to exclude certain properties. | #### `@createsOrReplacesResource` @@ -267,9 +267,9 @@ Mark this model as a resource type with a name. ##### Parameters -| Name | Type | Description | -| -------------- | ----------------------- | ---------------------- | -| collectionName | `valueof scalar string` | type's collection name | +| Name | Type | Description | +| -------------- | ---------------- | ---------------------- | +| collectionName | `valueof string` | type's collection name | #### `@segment` @@ -281,13 +281,13 @@ Defines the preceding path segment for a ##### Target -`union Model | ModelProperty | Operation` +`Model | ModelProperty | Operation` ##### Parameters -| Name | Type | Description | -| ---- | ----------------------- | ---------------------------------------------------------------------------------------------- | -| name | `valueof scalar string` | Segment that will be inserted into the operation route before the path parameter's name field. | +| Name | Type | Description | +| ---- | ---------------- | ---------------------------------------------------------------------------------------------- | +| name | `valueof string` | Segment that will be inserted into the operation route before the path parameter's name field. | ##### Examples diff --git a/packages/rest/package.json b/packages/rest/package.json index 2389ca1e81..8d3bdfae3a 100644 --- a/packages/rest/package.json +++ b/packages/rest/package.json @@ -38,6 +38,7 @@ "watch": "tsc -p . --watch", "lint-typespec-library": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit", "test": "vitest run", + "test:watch": "vitest --watch", "test:ui": "vitest --ui", "test-official": "vitest run --coverage --reporter=junit --reporter=default --no-file-parallelism", "lint": "eslint . --ext .ts --max-warnings=0", diff --git a/packages/rest/test/routes.test.ts b/packages/rest/test/routes.test.ts index 7e7be9ba95..b070d47419 100644 --- a/packages/rest/test/routes.test.ts +++ b/packages/rest/test/routes.test.ts @@ -425,7 +425,7 @@ describe("rest: routes", () => { strictEqual(diagnostics[0].code, "invalid-argument"); strictEqual( diagnostics[0].message, - `Argument 'x' is not assignable to parameter of type 'valueof / | : | /:'` + `Argument '"x"' is not assignable to parameter of type 'valueof "/" | ":" | "/:"'` ); }); diff --git a/packages/tspd/package.json b/packages/tspd/package.json index 3b4403d027..99631cc901 100644 --- a/packages/tspd/package.json +++ b/packages/tspd/package.json @@ -44,6 +44,7 @@ "build": "tsc -p .", "watch": "tsc -p . --watch", "test": "vitest run", + "test:watch": "vitest --watch", "test:ui": "vitest --ui", "test-official": "vitest run --coverage --reporter=junit --reporter=default --no-file-parallelism", "lint": "eslint . --ext .ts --max-warnings=0", diff --git a/packages/tspd/src/ref-doc/emitters/docusaurus.ts b/packages/tspd/src/ref-doc/emitters/docusaurus.ts index 89c817f1c6..585ffb0823 100644 --- a/packages/tspd/src/ref-doc/emitters/docusaurus.ts +++ b/packages/tspd/src/ref-doc/emitters/docusaurus.ts @@ -1,5 +1,6 @@ import { NamedTypeRefDoc, + RefDocEntity, TypeSpecLibraryRefDoc, TypeSpecRefDoc, TypeSpecRefDocBase, @@ -72,25 +73,19 @@ function renderIndexFile(renderer: DocusaurusRenderer, refDoc: TypeSpecLibraryRe const content = []; if (namespace.decorators.length > 0) { - content.push( - section("Decorators", renderer.toc(namespace.decorators, "./decorators.md")) - ); + content.push(section("Decorators", renderer.toc(namespace.decorators))); } if (namespace.interfaces.length > 0) { - content.push( - section("Interfaces", renderer.toc(namespace.interfaces, "./interfaces.md")) - ); + content.push(section("Interfaces", renderer.toc(namespace.interfaces))); } if (namespace.operations.length > 0) { - content.push( - section("Operations", renderer.toc(namespace.operations, "./interfaces.md")) - ); + content.push(section("Operations", renderer.toc(namespace.operations))); } if (namespace.models.length > 0) { - content.push(section("Models", renderer.toc(namespace.models, "./data-types.md"))); + content.push(section("Models", renderer.toc(namespace.models))); } return content; }), @@ -255,11 +250,6 @@ function renderLinter( } export class DocusaurusRenderer extends MarkdownRenderer { - #refDoc: TypeSpecLibraryRefDoc; - constructor(refDoc: TypeSpecLibraryRefDoc) { - super(); - this.#refDoc = refDoc; - } headingTitle(item: NamedTypeRefDoc): string { // Set an explicit anchor id. return `${inlinecode(item.name)} {#${item.id}}`; @@ -287,8 +277,24 @@ export class DocusaurusRenderer extends MarkdownRenderer { ); } + filename(type: RefDocEntity): string { + switch (type.kind) { + case "decorator": + return "./decorators.md"; + case "operation": + case "interface": + return "./interfaces.md"; + case "model": + case "enum": + case "union": + return "./data-types.md"; + default: + return ""; + } + } + linterRuleLink(url: string) { - const homepage = (this.#refDoc.packageJson as any).docusaurusWebsite; + const homepage = (this.refDoc.packageJson as any).docusaurusWebsite; if (homepage && url.includes(homepage)) { const fromRoot = url.replace(homepage, ""); return `${fromRoot}.md`; diff --git a/packages/tspd/src/ref-doc/emitters/markdown.ts b/packages/tspd/src/ref-doc/emitters/markdown.ts index 9bd8eab608..0ef1f0b7ef 100644 --- a/packages/tspd/src/ref-doc/emitters/markdown.ts +++ b/packages/tspd/src/ref-doc/emitters/markdown.ts @@ -1,4 +1,4 @@ -import { resolvePath } from "@typespec/compiler"; +import { Type, ValueType, getTypeName, resolvePath } from "@typespec/compiler"; import { readFile } from "fs/promises"; import { stringify } from "yaml"; import { @@ -8,10 +8,12 @@ import { ExampleRefDoc, InterfaceRefDoc, LinterRuleRefDoc, + ModelPropertyRefDoc, ModelRefDoc, NamedTypeRefDoc, NamespaceRefDoc, OperationRefDoc, + RefDocEntity, ReferencableElement, ScalarRefDoc, TemplateParameterRefDoc, @@ -28,7 +30,6 @@ import { section, table, } from "../utils/markdown.js"; -import { getTypeSignature } from "../utils/type-signature.js"; async function loadTemplate(projectRoot: string, name: string) { try { @@ -44,7 +45,7 @@ async function loadTemplate(projectRoot: string, name: string) { export async function renderReadme(refDoc: TypeSpecRefDoc, projectRoot: string) { const content: MarkdownDoc[] = []; - const renderer = new MarkdownRenderer(); + const renderer = new MarkdownRenderer(refDoc); if (refDoc.description) { content.push(refDoc.description); @@ -72,7 +73,7 @@ export async function renderReadme(refDoc: TypeSpecRefDoc, projectRoot: string) } export function groupByNamespace( - namespaces: NamespaceRefDoc[], + namespaces: readonly NamespaceRefDoc[], callback: (namespace: NamespaceRefDoc) => MarkdownDoc | undefined ): MarkdownDoc { const content: MarkdownDoc = []; @@ -89,6 +90,7 @@ export function groupByNamespace( * Github flavored markdown renderer. */ export class MarkdownRenderer { + constructor(protected readonly refDoc: TypeSpecRefDoc) {} headingTitle(item: NamedTypeRefDoc): string { return inlinecode(item.name); } @@ -136,10 +138,75 @@ export class MarkdownRenderer { } content.push(this.examples(model.examples)); - + content.push(this.modelProperties(model)); return section(this.headingTitle(model), content); } + modelProperties(model: ModelRefDoc) { + const content: MarkdownDoc = []; + if (model.properties.size === 0 && model.type.indexer === undefined) { + return section("Properties", "None"); + } + const rows: { name: string; type: string; doc: string }[] = [ + { name: "Name", type: "Type", doc: "Description" }, + ]; + + for (const prop of model.properties.values()) { + const propRows = this.modelPropertyRows(prop); + for (const row of propRows) { + rows.push(row); + } + } + if (model.type.indexer) { + rows.push({ + name: "", + type: this.ref(model.type.indexer.value), + doc: "Additional properties", + }); + } + content.push(table(rows.map((x) => [x.name, x.type, x.doc]))); + return section("Properties", content); + } + + modelPropertyRows(prop: ModelPropertyRefDoc): { name: string; type: string; doc: string }[] { + const base = { + name: `${prop.name}${prop.type.optional ? "?" : ""}`, + type: this.ref(prop.type.type), + doc: prop.doc, + }; + if (prop.type.type.kind === "Model" && prop.type.type.name === "") { + return [ + base, + ...[...prop.type.type.properties.values()].map((x) => ({ + name: `${prop.name}.${x.name}${x.optional ? "?" : ""}`, + type: this.ref(x.type), + doc: "", + })), + ]; + } + return [base]; + } + + ref(type: Type | ValueType): string { + const namedType = type.kind !== "Value" && this.refDoc.getNamedTypeRefDoc(type); + if (namedType) { + return link( + inlinecode(namedType.name), + `${this.filename(namedType)}#${this.anchorId(namedType)}` + ); + } + + // So we don't show (anonymous model) until this gets improved. + if (type.kind === "Model" && type.name === "" && type.properties.size > 0) { + return inlinecode("{...}"); + } + return inlinecode( + getTypeName(type, { + namespaceFilter: (ns) => !this.refDoc.namespaces.some((x) => x.name === ns.name), + }) + ); + } + enum(e: EnumRefDoc): MarkdownDoc { const content: MarkdownDoc = [ "", @@ -176,7 +243,7 @@ export class MarkdownRenderer { return section(this.headingTitle(scalar), content); } - templateParameters(templateParameters: TemplateParameterRefDoc[]): MarkdownDoc { + templateParameters(templateParameters: readonly TemplateParameterRefDoc[]): MarkdownDoc { const paramTable: string[][] = [["Name", "Description"]]; for (const param of templateParameters) { paramTable.push([param.name, param.doc]); @@ -188,14 +255,12 @@ export class MarkdownRenderer { decorator(dec: DecoratorRefDoc) { const content: MarkdownDoc = ["", dec.doc, codeblock(dec.signature, "typespec"), ""]; - content.push( - section("Target", [dec.target.doc, inlinecode(getTypeSignature(dec.target.type.type)), ""]) - ); + content.push(section("Target", [dec.target.doc, this.ref(dec.target.type.type), ""])); if (dec.parameters.length > 0) { const paramTable: string[][] = [["Name", "Type", "Description"]]; for (const param of dec.parameters) { - paramTable.push([param.name, inlinecode(getTypeSignature(param.type.type)), param.doc]); + paramTable.push([param.name, this.ref(param.type.type), param.doc]); } content.push(section("Parameters", [table(paramTable), ""])); } else { @@ -207,7 +272,7 @@ export class MarkdownRenderer { return section(this.headingTitle(dec), content); } - examples(examples: ExampleRefDoc[]) { + examples(examples: readonly ExampleRefDoc[]) { const content: MarkdownDoc = []; if (examples.length === 0) { return ""; @@ -241,12 +306,16 @@ export class MarkdownRenderer { }); } - toc(items: ReferencableElement[], filename?: string) { + toc(items: readonly (ReferencableElement & RefDocEntity)[]) { return items.map( - (item) => ` - [${inlinecode(item.name)}](${filename ?? ""}#${this.anchorId(item)})` + (item) => ` - [${inlinecode(item.name)}](${this.filename(item)}#${this.anchorId(item)})` ); } + filename(type: ReferencableElement & RefDocEntity): string { + return ""; + } + install(refDoc: TypeSpecRefDoc) { return section("Install", [codeblock(`npm install ${refDoc.name}`, "bash")]); } diff --git a/packages/tspd/src/ref-doc/extractor.ts b/packages/tspd/src/ref-doc/extractor.ts index 4e6e7f172e..9e13411167 100644 --- a/packages/tspd/src/ref-doc/extractor.ts +++ b/packages/tspd/src/ref-doc/extractor.ts @@ -20,6 +20,7 @@ import { LinterRuleDefinition, LinterRuleSet, Model, + ModelProperty, Namespace, navigateProgram, navigateTypesInNamespace, @@ -49,9 +50,11 @@ import { LinterRefDoc, LinterRuleRefDoc, LinterRuleSetRefDoc, + ModelPropertyRefDoc, ModelRefDoc, NamespaceRefDoc, OperationRefDoc, + RefDocEntity, ScalarRefDoc, TypeSpecLibraryRefDoc, TypeSpecRefDocBase, @@ -59,23 +62,37 @@ import { } from "./types.js"; import { getQualifier, getTypeSignature } from "./utils/type-signature.js"; +/** + * The mutable equivalent of a type. + */ + +//prettier-ignore +type Mutable = + T extends ReadonlyMap ? Map : + T extends ReadonlySet ? Set> : + T extends readonly (infer V)[] ? V[] : + // brand to force explicit conversion. + { -readonly [P in keyof T]: T[P]}; + export async function extractLibraryRefDocs( libraryPath: string ): Promise<[TypeSpecLibraryRefDoc, readonly Diagnostic[]]> { const diagnostics = createDiagnosticCollector(); const pkgJson = await readPackageJson(libraryPath); - const refDoc: TypeSpecLibraryRefDoc = { + const refDoc: Mutable = { name: pkgJson.name, description: pkgJson.description, packageJson: pkgJson, namespaces: [], + getNamedTypeRefDoc: (type) => undefined, }; if (pkgJson.tspMain) { const main = resolvePath(libraryPath, pkgJson.tspMain); const program = await compile(NodeHost, main, { parseOptions: { comments: true, docs: true }, }); - refDoc.namespaces = diagnostics.pipe(extractRefDocs(program)).namespaces; + const tspEmitter = diagnostics.pipe(extractRefDocs(program)); + Object.assign(refDoc, tspEmitter); for (const diag of program.diagnostics ?? []) { diagnostics.add(diag); } @@ -143,20 +160,22 @@ function resolveNamespaces( } return diagnostics.wrap(namespaceTypes); } + export function extractRefDocs( program: Program, options: ExtractRefDocOptions = {} ): [TypeSpecRefDocBase, readonly Diagnostic[]] { const diagnostics = createDiagnosticCollector(); const namespaceTypes = diagnostics.pipe(resolveNamespaces(program, options)); - - const refDoc: TypeSpecRefDocBase = { - namespaces: [], - }; + const typeMapping = new Map(); + const namespaces: Mutable[] = []; for (const namespace of namespaceTypes) { - const namespaceDoc: NamespaceRefDoc = { - id: getTypeName(namespace), + const name = getTypeName(namespace); + const namespaceDoc: Mutable = { + kind: "namespace", + id: name, + name, decorators: [], operations: [], interfaces: [], @@ -166,26 +185,35 @@ export function extractRefDocs( scalars: [], }; - refDoc.namespaces.push(namespaceDoc); + namespaces.push(namespaceDoc); + function collectType(type: Type, refDoc: T, array: T[] | readonly T[]) { + typeMapping.set(type, refDoc); + (array as any).push(refDoc); + } navigateTypesInNamespace( namespace, { decorator(dec) { - namespaceDoc.decorators.push(extractDecoratorRefDoc(program, dec)); + collectType(dec, extractDecoratorRefDoc(program, dec), namespaceDoc.decorators); }, operation(operation) { if (!isDeclaredType(operation)) { return; } + if (operation.interface === undefined) { - namespaceDoc.operations.push(extractOperationRefDoc(program, operation, undefined)); + collectType( + operation, + extractOperationRefDoc(program, operation, undefined), + namespaceDoc.operations + ); } }, interface(iface) { if (!isDeclaredType(iface)) { return; } - namespaceDoc.interfaces.push(extractInterfaceRefDocs(program, iface)); + collectType(iface, extractInterfaceRefDocs(program, iface), namespaceDoc.interfaces); }, model(model) { if (!isDeclaredType(model)) { @@ -194,32 +222,32 @@ export function extractRefDocs( if (model.name === "") { return; } - namespaceDoc.models.push(extractModelRefDocs(program, model)); + collectType(model, extractModelRefDocs(program, model), namespaceDoc.models); }, enum(e) { if (!isDeclaredType(e)) { return; } - namespaceDoc.enums.push(extractEnumRefDoc(program, e)); + collectType(e, extractEnumRefDoc(program, e), namespaceDoc.enums); }, union(union) { if (!isDeclaredType(union)) { return; } if (union.name !== undefined) { - namespaceDoc.unions.push(extractUnionRefDocs(program, union as any)); + collectType(union, extractUnionRefDocs(program, union as any), namespaceDoc.unions); } }, scalar(scalar) { - namespaceDoc.scalars.push(extractScalarRefDocs(program, scalar as any)); + collectType(scalar, extractScalarRefDocs(program, scalar), namespaceDoc.scalars); }, }, { includeTemplateDeclaration: true, skipSubNamespaces: true } ); } - sort(refDoc.namespaces); - for (const namespace of refDoc.namespaces) { + sort(namespaces); + for (const namespace of namespaces) { sort(namespace.decorators); sort(namespace.enums); sort(namespace.interfaces); @@ -229,11 +257,14 @@ export function extractRefDocs( sort(namespace.scalars); } - function sort(arr: { id: string }[]) { - arr.sort((a, b) => a.id.localeCompare(b.id, "en")); + function sort(arr: { id: string }[] | readonly { id: string }[]) { + (arr as { id: string }[]).sort((a, b) => a.id.localeCompare(b.id, "en")); } - return diagnostics.wrap(refDoc); + return diagnostics.wrap({ + namespaces, + getNamedTypeRefDoc: (type) => typeMapping.get(type), + }); } function extractTemplateParameterDocs(program: Program, type: TemplatedType) { @@ -270,6 +301,7 @@ function extractInterfaceRefDocs(program: Program, iface: Interface): InterfaceR }); } return { + kind: "interface", id: getNamedTypeId(iface), name: iface.name, signature: getTypeSignature(iface), @@ -307,6 +339,7 @@ function extractOperationRefDoc( } } return { + kind: "operation", id: getNamedTypeId(operation), name: interfaceName ? `${interfaceName}.${operation.name}` : operation.name, signature: getTypeSignature(operation), @@ -330,6 +363,7 @@ function extractDecoratorRefDoc(program: Program, decorator: Decorator): Decorat }); } return { + kind: "decorator", type: x, doc: paramDoc.get(x.name) ?? "", name: x.name, @@ -349,6 +383,7 @@ function extractDecoratorRefDoc(program: Program, decorator: Decorator): Decorat }); } return { + kind: "decorator", id: getNamedTypeId(decorator), name: decorator.name, type: decorator, @@ -378,6 +413,7 @@ function extractModelRefDocs(program: Program, type: Model): ModelRefDoc { }); } return { + kind: "model", id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), @@ -385,6 +421,21 @@ function extractModelRefDocs(program: Program, type: Model): ModelRefDoc { templateParameters: extractTemplateParameterDocs(program, type), doc: doc, examples: extractExamples(type), + properties: new Map( + [...type.properties.values()].map((x) => [x.name, extractModelPropertyRefDocs(program, x)]) + ), + }; +} + +function extractModelPropertyRefDocs(program: Program, type: ModelProperty): ModelPropertyRefDoc { + const doc = extractMainDoc(program, type); + return { + id: getNamedTypeId(type), + name: type.name, + signature: getTypeSignature(type), + type, + doc: doc, + examples: extractExamples(type), }; } @@ -399,6 +450,7 @@ function extractEnumRefDoc(program: Program, type: Enum): EnumRefDoc { }); } return { + kind: "enum", id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), @@ -418,6 +470,7 @@ function extractUnionRefDocs(program: Program, type: Union & { name: string }): }); } return { + kind: "union", id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), @@ -439,6 +492,7 @@ function extractScalarRefDocs(program: Program, type: Scalar): ScalarRefDoc { }); } return { + kind: "scalar", id: getNamedTypeId(type), name: type.name, signature: getTypeSignature(type), @@ -449,13 +503,13 @@ function extractScalarRefDocs(program: Program, type: Scalar): ScalarRefDoc { } function extractMainDoc(program: Program, type: Type): string { - let mainDoc: string = ""; + const mainDocs: string[] = []; for (const doc of type.node?.docs ?? []) { for (const dContent of doc.content) { - mainDoc += dContent.text + "\n"; + mainDocs.push(dContent.text); } } - return mainDoc !== "" ? mainDoc : getDoc(program, type) ?? ""; + return mainDocs.length > 0 ? mainDocs.join("\n") : getDoc(program, type) ?? ""; } function extractExamples(type: Type): ExampleRefDoc[] { @@ -582,6 +636,7 @@ function extractLinterRuleSetsRefDoc( return Object.entries(ruleSets).map(([name, ruleSet]) => { const fullName = `${libName}/${name}`; return { + kind: "ruleset", id: fullName, name: fullName, ruleSet, @@ -594,6 +649,7 @@ function extractLinterRuleRefDoc( ): LinterRuleRefDoc { const fullName = `${libName}/${rule.name}`; return { + kind: "rule", id: fullName, name: fullName, rule, diff --git a/packages/tspd/src/ref-doc/types.ts b/packages/tspd/src/ref-doc/types.ts index 842e05eedd..e39fe0b2ee 100644 --- a/packages/tspd/src/ref-doc/types.ts +++ b/packages/tspd/src/ref-doc/types.ts @@ -6,9 +6,11 @@ import { LinterRuleDefinition, LinterRuleSet, Model, + ModelProperty, NodePackage, Operation, Scalar, + Type, Union, } from "@typespec/compiler"; @@ -18,133 +20,162 @@ export type TypeSpecLibraryRefDoc = TypeSpecRefDocBase & { /** * Library name */ - name: string; + readonly name: string; /** * Library package.json */ - packageJson: NodePackage; + readonly packageJson: NodePackage; /** * Library description */ - description?: string; + readonly description?: string; - emitter?: EmitterRefDoc; + readonly emitter?: EmitterRefDoc; /** Documentation about the linter rules and ruleset provided in this library. */ - linter?: LinterRefDoc; + readonly linter?: LinterRefDoc; }; export type TypeSpecRefDocBase = { - namespaces: NamespaceRefDoc[]; + readonly namespaces: readonly NamespaceRefDoc[]; + + /** Returns the named type ref doc mapping to that type if is is part of this library. */ + readonly getNamedTypeRefDoc: (type: Type) => RefDocEntity | undefined; }; export type EmitterRefDoc = { - options: EmitterOptionRefDoc[]; + readonly options: EmitterOptionRefDoc[]; }; export type LinterRefDoc = { /** List of rulesets provided. */ - ruleSets?: LinterRuleSetRefDoc[]; - rules: LinterRuleRefDoc[]; + readonly ruleSets?: LinterRuleSetRefDoc[]; + readonly rules: LinterRuleRefDoc[]; }; export type LinterRuleSetRefDoc = ReferencableElement & { - ruleSet: LinterRuleSet; + readonly kind: "ruleset"; + readonly ruleSet: LinterRuleSet; }; export type LinterRuleRefDoc = ReferencableElement & { - rule: LinterRuleDefinition; + readonly kind: "rule"; + readonly rule: LinterRuleDefinition; }; export type EmitterOptionRefDoc = { - name: string; - type: string; - doc: string; -}; + readonly name: string; + readonly type: string; + readonly doc: string; +}; + +export type RefDocEntity = + | NamespaceRefDoc + | DecoratorRefDoc + | OperationRefDoc + | InterfaceRefDoc + | ModelRefDoc + | EnumRefDoc + | UnionRefDoc + | ScalarRefDoc + | LinterRuleSetRefDoc + | LinterRuleRefDoc; export type NamespaceRefDoc = { - id: string; - decorators: DecoratorRefDoc[]; - operations: OperationRefDoc[]; - interfaces: InterfaceRefDoc[]; - models: ModelRefDoc[]; - enums: EnumRefDoc[]; - unions: UnionRefDoc[]; - scalars: ScalarRefDoc[]; + readonly kind: "namespace"; + readonly id: string; + readonly name: string; + readonly decorators: readonly DecoratorRefDoc[]; + readonly operations: readonly OperationRefDoc[]; + readonly interfaces: readonly InterfaceRefDoc[]; + readonly models: readonly ModelRefDoc[]; + readonly enums: readonly EnumRefDoc[]; + readonly unions: readonly UnionRefDoc[]; + readonly scalars: readonly ScalarRefDoc[]; }; export type ReferencableElement = { /** * Fully qualified id */ - id: string; + readonly id: string; - name: string; + readonly name: string; }; export type NamedTypeRefDoc = ReferencableElement & { - signature: string; - doc: string; - examples: ExampleRefDoc[]; + readonly signature: string; + readonly doc: string; + readonly examples: readonly ExampleRefDoc[]; }; export type DecoratorRefDoc = NamedTypeRefDoc & { - type: Decorator; - target: FunctionParameterRefDoc; - parameters: FunctionParameterRefDoc[]; - otherTags: string[]; + readonly kind: "decorator"; + readonly type: Decorator; + readonly target: FunctionParameterRefDoc; + readonly parameters: readonly FunctionParameterRefDoc[]; + readonly otherTags: readonly string[]; }; export type FunctionParameterRefDoc = { - type: FunctionParameter; - name: string; - doc: string; - optional: boolean; - rest: boolean; + readonly type: FunctionParameter; + readonly name: string; + readonly doc: string; + readonly optional: boolean; + readonly rest: boolean; }; export type ExampleRefDoc = { - title?: string; - content: string; + readonly title?: string; + readonly content: string; }; export type OperationRefDoc = NamedTypeRefDoc & { - type: Operation; - - templateParameters?: TemplateParameterRefDoc[]; + readonly kind: "operation"; + readonly type: Operation; + readonly templateParameters?: TemplateParameterRefDoc[]; }; export type InterfaceRefDoc = NamedTypeRefDoc & { - type: Interface; - templateParameters?: TemplateParameterRefDoc[]; - - interfaceOperations: OperationRefDoc[]; + readonly kind: "interface"; + readonly type: Interface; + readonly templateParameters?: readonly TemplateParameterRefDoc[]; + readonly interfaceOperations: readonly OperationRefDoc[]; }; export type TemplateParameterRefDoc = { - name: string; - doc: string; + readonly name: string; + readonly doc: string; }; export type ModelRefDoc = NamedTypeRefDoc & { - type: Model; + readonly kind: "model"; + readonly type: Model; + + readonly templateParameters?: readonly TemplateParameterRefDoc[]; + readonly properties: ReadonlyMap; +}; - templateParameters?: TemplateParameterRefDoc[]; +export type ModelPropertyRefDoc = NamedTypeRefDoc & { + readonly type: ModelProperty; }; export type EnumRefDoc = NamedTypeRefDoc & { - type: Enum; + readonly kind: "enum"; + readonly type: Enum; }; export type UnionRefDoc = NamedTypeRefDoc & { - type: Union; + readonly kind: "union"; + readonly type: Union; - templateParameters?: TemplateParameterRefDoc[]; + readonly templateParameters?: readonly TemplateParameterRefDoc[]; }; export type ScalarRefDoc = NamedTypeRefDoc & { - type: Scalar; + readonly kind: "scalar"; + readonly type: Scalar; - templateParameters?: TemplateParameterRefDoc[]; + readonly templateParameters?: readonly TemplateParameterRefDoc[]; }; diff --git a/packages/tspd/test/emitters/markdown/model.test.ts b/packages/tspd/test/emitters/markdown/model.test.ts new file mode 100644 index 0000000000..07ea032c54 --- /dev/null +++ b/packages/tspd/test/emitters/markdown/model.test.ts @@ -0,0 +1,220 @@ +import { ok } from "assert"; +import { describe, expect, it } from "vitest"; +import { renderMarkdowDoc } from "../../../src/ref-doc/utils/markdown.js"; +import { createMarkdownRenderer } from "../../test-utils.js"; + +async function renderModel(code: string) { + const { renderer, refDoc } = await createMarkdownRenderer(`namespace Lib; ${code}`); + const fooModel = refDoc.namespaces[0].models.find((x) => x.name === "Test"); + ok(fooModel, "Expected a model named `Test`"); + return renderMarkdowDoc(renderer.model(fooModel)); +} + +it("render simple model", async () => { + const result = await renderModel(`model Test {}`); + expect(result).toEqual( + [ + "# `Test`", + "", + "", + "```typespec", + "model Lib.Test", + "```", + "", + "", + "## Properties", + "None", + ].join("\n") + ); +}); + +it("render model with template parameter", async () => { + const result = await renderModel(`model Test {}`); + expect(result).toEqual( + [ + "# `Test`", + "", + "", + "```typespec", + "model Lib.Test", + "```", + "", + "## Template Parameters", + "| Name | Description |", + "|------|-------------|", + "| T | |", + "", + "", + "## Properties", + "None", + ].join("\n") + ); +}); + +describe("model examples", () => { + it("render single example", async () => { + const result = await renderModel(` + /** + * @example + * \`\`\`tsp + * model Foo {test: Test} + * \`\`\` + */ + model Test {} + `); + expect(result).toEqual( + [ + "# `Test`", + "", + "", + "", + "```typespec", + "model Lib.Test", + "```", + "", + "## Examples", + "", + "```tsp", + "model Foo {test: Test}", + "```", + "", + "## Properties", + "None", + ].join("\n") + ); + }); + + it("render named example", async () => { + const result = await renderModel(` + /** + * @example First Example + * \`\`\`tsp + * model Foo {test1: Test} + * \`\`\` + * @example Second Example + * \`\`\`tsp + * model Foo {test2: Test} + * \`\`\` + */ + model Test {} + `); + expect(result).toEqual( + [ + "# `Test`", + "", + "", + "", + "```typespec", + "model Lib.Test", + "```", + "", + "## Examples", + "### First Example", + "", + "```tsp", + "model Foo {test1: Test}", + "```", + "", + "### Second Example", + "", + "```tsp", + "model Foo {test2: Test}", + "```", + "", + "## Properties", + "None", + ].join("\n") + ); + }); +}); + +describe("properties table", () => { + const common = [ + "# `Test`", + "", + "", + "```typespec", + "model Lib.Test", + "```", + "", + "", + "## Properties", + "| Name | Type | Description |", + "|------|------|-------------|", + ]; + async function expectTable({ code, rows }: { code: string; rows: string[] }) { + const result = await renderModel(code); + expect(result).toEqual([...common, ...rows].join("\n")); + } + it("render properties without docs", async () => { + await expectTable({ + code: `model Test { name: string, other: int32 }`, + rows: ["| name | `string` | |", "| other | `int32` | |"], + }); + }); + + it("render enum properties", async () => { + await expectTable({ + code: ` + model Test { name: Bar.baz } + enum Bar { baz } + `, + rows: ["| name | `Bar.baz` | |"], + }); + }); + + it("render array properties", async () => { + await expectTable({ + code: ` + model Test { name: string[] } + `, + rows: ["| name | `string[]` | |"], + }); + }); + + it("render properties with documentation", async () => { + await expectTable({ + code: `model Test { + /** name of the test */ + name: string; + /** other of the test */ + other: int32; + }`, + rows: ["| name | `string` | name of the test |", "| other | `int32` | other of the test |"], + }); + }); + + it("render optional properties", async () => { + await expectTable({ + code: `model Test { name?: string, other: int32 }`, + rows: ["| name? | `string` | |", "| other | `int32` | |"], + }); + }); + + it("render link to local type", async () => { + await expectTable({ + code: `model Test { other: Other } model Other {name: string}`, + rows: ["| other | [`Other`](#other) | |"], + }); + }); + + it("render indexer", async () => { + await expectTable({ + code: `model Test is Record { name: string }`, + rows: ["| name | `string` | |", "| | `string` | Additional properties |"], + }); + }); + + it("flatten nested anonymous model", async () => { + await expectTable({ + code: `model Test { name: string, nested: {val: string, age: int32, third?: boolean} }`, + rows: [ + "| name | `string` | |", + "| nested | `{...}` | |", + "| nested.val | `string` | |", + "| nested.age | `int32` | |", + "| nested.third? | `boolean` | |", + ], + }); + }); +}); diff --git a/packages/tspd/test/test-utils.ts b/packages/tspd/test/test-utils.ts new file mode 100644 index 0000000000..526f8c5e4f --- /dev/null +++ b/packages/tspd/test/test-utils.ts @@ -0,0 +1,16 @@ +import { createTestHost, expectDiagnosticEmpty } from "@typespec/compiler/testing"; +import { MarkdownRenderer } from "../src/ref-doc/emitters/markdown.js"; +import { extractRefDocs } from "../src/ref-doc/extractor.js"; + +export async function extractTestRefDoc(code: string) { + const host = await createTestHost(); + host.addTypeSpecFile("main.tsp", code); + await host.compile("main.tsp"); + return extractRefDocs(host.program); +} + +export async function createMarkdownRenderer(code: string) { + const [refDoc, diagnostics] = await extractTestRefDoc(code); + expectDiagnosticEmpty(diagnostics); + return { renderer: new MarkdownRenderer(refDoc as any), refDoc }; +} diff --git a/packages/versioning/README.md b/packages/versioning/README.md index 22d0b9eca8..abb940eab7 100644 --- a/packages/versioning/README.md +++ b/packages/versioning/README.md @@ -67,7 +67,7 @@ Identifies when the target was added. ##### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` ##### Parameters @@ -131,7 +131,7 @@ Identifies when the target was removed. ##### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` ##### Parameters @@ -166,14 +166,14 @@ Identifies when the target has been renamed. ##### Target -`union Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` +`Model | ModelProperty | Operation | Enum | EnumMember | Union | UnionVariant | Scalar | Interface` ##### Parameters -| Name | Type | Description | -| ------- | ----------------------- | ------------------------------------------- | -| version | `EnumMember` | The version that the target was renamed in. | -| oldName | `valueof scalar string` | The previous name of the target. | +| Name | Type | Description | +| ------- | ---------------- | ------------------------------------------- | +| version | `EnumMember` | The version that the target was renamed in. | +| oldName | `valueof string` | The previous name of the target. | ##### Examples @@ -196,10 +196,10 @@ Identifies when the target type changed. ##### Parameters -| Name | Type | Description | -| ------- | --------------------- | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `(intrinsic) unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | -------------------------------------------- | +| version | `EnumMember` | The version that the target type changed in. | +| oldType | `unknown` | The previous type of the target. | #### `@typeChangedFrom` @@ -215,10 +215,10 @@ Identifies when the target type changed. ##### Parameters -| Name | Type | Description | -| ------- | --------------------- | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `(intrinsic) unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | -------------------------------------------- | +| version | `EnumMember` | The version that the target type changed in. | +| oldType | `unknown` | The previous type of the target. | #### `@useDependency` @@ -230,13 +230,13 @@ Identifies that a namespace or a given versioning enum member relies upon a vers ##### Target -`union EnumMember | Namespace` +`EnumMember | Namespace` ##### Parameters -| Name | Type | Description | -| -------------- | -------------------- | --------------------------------------------------------------------- | -| versionRecords | `model EnumMember[]` | The dependent library version(s) for the target namespace or version. | +| Name | Type | Description | +| -------------- | -------------- | --------------------------------------------------------------------- | +| versionRecords | `EnumMember[]` | The dependent library version(s) for the target namespace or version. | ##### Examples diff --git a/packages/website/.scripts/regen-compiler-docs.mjs b/packages/website/.scripts/regen-compiler-docs.mjs index 8d051d898e..2833576bd4 100644 --- a/packages/website/.scripts/regen-compiler-docs.mjs +++ b/packages/website/.scripts/regen-compiler-docs.mjs @@ -17,6 +17,26 @@ export const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../ const diagnostics = new Map(); +class CompilerDocusaurusRenderer extends DocusaurusRenderer { + /** + * @param {import("../../tspd/dist/src/ref-doc/types.js").RefDocEntity} type + */ + filename(type) { + switch (type.kind) { + case "decorator": + return "./built-in-decorators.md"; + case "model": + case "enum": + case "union": + return "./built-in-data-types.md"; + case "operation": + case "interface": + default: + return ""; + } + } +} + // Compiler const compilerDiag = await generateCompilerDocs(); if (compilerDiag.length) { @@ -39,9 +59,10 @@ async function generateCompilerDocs() { const results = await resolveLibraryRefDocsBase(compilerPath, { namespaces: { include: ["TypeSpec"] }, }); - const renderer = new DocusaurusRenderer(); assert(results, "Unexpected ref doc should have been resolved for compiler."); + /** @type {*} */ const [refDoc, diagnostics] = results; + const renderer = new CompilerDocusaurusRenderer(refDoc); const decoratorContent = renderDecoratorFile(renderer, refDoc, { title: "Built-in Decorators" }); assert(decoratorContent, "Unexpected decorator file shouldn't be empty for compiler."); await writeFile(join(outputDir, "built-in-decorators.md"), decoratorContent); diff --git a/packages/website/.scripts/tsconfig.json b/packages/website/.scripts/tsconfig.json index c9961df8a3..a7730eb755 100644 --- a/packages/website/.scripts/tsconfig.json +++ b/packages/website/.scripts/tsconfig.json @@ -1,5 +1,5 @@ { - "extends": "../../tsconfig.json", + "extends": "../../../tsconfig.base.json", "compilerOptions": { "allowJs": true },