Skip to content

Commit

Permalink
Regen ref docs with new model docs (#307)
Browse files Browse the repository at this point in the history
  • Loading branch information
@timotheeguerin
timotheeguerin authored Feb 29, 2024
1 parent a7175f2 commit 8b79de7
Show file tree
Hide file tree
Showing 17 changed files with 1,435 additions and 354 deletions.
10 changes: 10 additions & 0 deletions .chronus/changes/uptake-ref-docs-models-2024-1-24-2-57-3.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
changeKind: internal
packages:
- "@azure-tools/typespec-azure-core"
- "@azure-tools/typespec-azure-portal-core"
- "@azure-tools/typespec-azure-resource-manager"
- "@azure-tools/typespec-client-generator-core"
- "@azure-tools/typespec-autorest"
---
2 changes: 1 addition & 1 deletion core
Submodule core updated 45 files
+13 −0 .chronus/changes/ref-docs-models-2024-1-23-22-27-5.md
+8 −0 .chronus/changes/ref-docs-models-2024-1-24-0-0-44.md
+183 −0 docs/libraries/http/reference/data-types.md
+27 −27 docs/libraries/http/reference/decorators.md
+6 −0 docs/libraries/json-schema/reference/data-types.md
+57 −57 docs/libraries/json-schema/reference/decorators.md
+26 −0 docs/libraries/openapi/reference/data-types.md
+16 −16 docs/libraries/openapi/reference/decorators.md
+5 −5 docs/libraries/openapi3/reference/decorators.md
+41 −0 docs/libraries/protobuf/reference/data-types.md
+14 −14 docs/libraries/protobuf/reference/decorators.md
+51 −0 docs/libraries/rest/reference/data-types.md
+21 −21 docs/libraries/rest/reference/decorators.md
+19 −19 docs/libraries/versioning/reference/decorators.md
+21 −38 docs/standard-library/built-in-data-types.md
+59 −98 docs/standard-library/built-in-decorators.md
+1 −1 packages/compiler/src/config/config-to-options.ts
+2 −2 packages/compiler/src/core/decorator-utils.ts
+1 −1 packages/compiler/src/core/diagnostics.ts
+1 −0 packages/compiler/src/core/helpers/type-name-utils.ts
+2 −2 packages/compiler/src/core/types.ts
+3 −3 packages/compiler/test/checker/model.test.ts
+4 −4 packages/compiler/test/checker/relation.test.ts
+1 −1 packages/compiler/test/checker/templates.test.ts
+2 −2 packages/compiler/test/decorators/decorators.test.ts
+27 −27 packages/http/README.md
+1 −2 packages/http/test/http-decorators.test.ts
+57 −57 packages/json-schema/README.md
+16 −16 packages/openapi/README.md
+1 −1 packages/openapi/src/decorators.ts
+5 −5 packages/openapi3/README.md
+14 −14 packages/protobuf/README.md
+21 −21 packages/rest/README.md
+1 −0 packages/rest/package.json
+1 −1 packages/rest/test/routes.test.ts
+1 −0 packages/tspd/package.json
+22 −16 packages/tspd/src/ref-doc/emitters/docusaurus.ts
+82 −13 packages/tspd/src/ref-doc/emitters/markdown.ts
+80 −24 packages/tspd/src/ref-doc/extractor.ts
+86 −55 packages/tspd/src/ref-doc/types.ts
+220 −0 packages/tspd/test/emitters/markdown/model.test.ts
+16 −0 packages/tspd/test/test-utils.ts
+19 −19 packages/versioning/README.md
+22 −1 packages/website/.scripts/regen-compiler-docs.mjs
+1 −1 packages/website/.scripts/tsconfig.json
16 changes: 8 additions & 8 deletions docs/emitters/typespec-autorest/reference/decorators.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,10 @@ toc_max_heading_level: 3

#### Parameters

| Name | Type | Description |
| --------- | ----------------------- | ---------------------------------------- |
| pathOrUri | `valueof scalar string` | path or Uri to the example file. |
| title | `valueof scalar string` | name or description of the example file. |
| Name | Type | Description |
| --------- | ---------------- | ---------------------------------------- |
| pathOrUri | `valueof string` | path or Uri to the example file. |
| title | `valueof string` | name or description of the example file. |

### `@useRef` {#@Autorest.useRef}

Expand All @@ -41,10 +41,10 @@ toc_max_heading_level: 3

#### Target

`union Model | ModelProperty`
`Model | ModelProperty`

#### Parameters

| Name | Type | Description |
| ------- | ----------------------- | --------------------------------- |
| jsonRef | `valueof scalar string` | path or Uri to an OpenAPI schema. |
| Name | Type | Description |
| ------- | ---------------- | --------------------------------- |
| jsonRef | `valueof string` | path or Uri to an OpenAPI schema. |
384 changes: 384 additions & 0 deletions docs/libraries/azure-core/reference/data-types.md
View file

Large diffs are not rendered by default.

76 changes: 38 additions & 38 deletions docs/libraries/azure-core/reference/decorators.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ Identifies a ModelProperty as containing the final location for the operation re

#### Parameters

| Name | Type | Description |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| finalResult | `union Model \| void` | Sets the expected return value for the final result. Overrides<br />any value provided in the decorated property, if the property uses ResourceLocation<Resource>. |
| Name | Type | Description |
| ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| finalResult | `Model \| void` | Sets the expected return value for the final result. Overrides<br />any value provided in the decorated property, if the property uses ResourceLocation<Resource>. |

### `@finalOperation` {#@Azure.Core.finalOperation}

Expand All @@ -43,7 +43,7 @@ Identifies that an operation is the final operation for an LRO.
| Name | Type | Description |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| linkedOperation | `Operation` | The linked Operation |
| parameters | `model {}` | Map of `RequestParameter<Name>` and/or `ResponseProperty<Name>` that will<br />be passed to the linked operation request. |
| parameters | `{}` | Map of `RequestParameter<Name>` and/or `ResponseProperty<Name>` that will<br />be passed to the linked operation request. |

### `@fixed` {#@Azure.Core.fixed}

Expand Down Expand Up @@ -89,7 +89,7 @@ Identifies an EnumMember as a long-running "Canceled" terminal state.

#### Target

`union EnumMember | UnionVariant`
`EnumMember | UnionVariant`

#### Parameters

Expand Down Expand Up @@ -124,7 +124,7 @@ Identifies an enum member as a long-running "Failed" terminal state.

#### Target

`union EnumMember | UnionVariant`
`EnumMember | UnionVariant`

#### Parameters

Expand Down Expand Up @@ -160,7 +160,7 @@ status.

#### Target

`union Enum | Union | ModelProperty`
`Enum | Union | ModelProperty`

#### Parameters

Expand All @@ -177,7 +177,7 @@ Identifies an EnumMember as a long-running "Succeeded" terminal state.

#### Target

`union EnumMember | UnionVariant`
`EnumMember | UnionVariant`

#### Parameters

Expand Down Expand Up @@ -216,7 +216,7 @@ Identifies that an operation is used to retrieve the next page for paged operati
| Name | Type | Description |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| linkedOperation | `Operation` | The linked Operation |
| parameters | `model {}` | Map of `RequestParameter<Name>` and/or `ResponseProperty<Name>` that will<br />be passed to the linked operation request. |
| parameters | `{}` | Map of `RequestParameter<Name>` and/or `ResponseProperty<Name>` that will<br />be passed to the linked operation request. |

### `@operationLink` {#@Azure.Core.operationLink}

Expand All @@ -232,11 +232,11 @@ Identifies an operation that is linked to the target operation.

#### Parameters

| Name | Type | Description |
| --------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| linkedOperation | `Operation` | The linked Operation |
| linkType | `valueof scalar string` | A string indicating the role of the linked operation |
| parameters | `model {}` | Map of `RequestParameter<Name>` and/or `ResponseProperty<Name>` that will<br />be passed to the linked operation request. |
| Name | Type | Description |
| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| linkedOperation | `Operation` | The linked Operation |
| linkType | `valueof string` | A string indicating the role of the linked operation |
| parameters | `{}` | Map of `RequestParameter<Name>` and/or `ResponseProperty<Name>` that will<br />be passed to the linked operation request. |

### `@pagedResult` {#@Azure.Core.pagedResult}

Expand Down Expand Up @@ -268,9 +268,9 @@ Identifies a model property as containing the location to poll for operation sta

#### Parameters

| Name | Type | Description |
| ------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| options | `model Azure.Core.PollingOptions` | PollingOptions for the poller pointed to by this link. Overrides<br />settings derived from property value it is decorating, if the value of the<br />property is ResourceLocation<Resource> |
| Name | Type | Description |
| ------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| options | [`PollingOptions`](./data-types.md#Azure.Core.PollingOptions) | PollingOptions for the poller pointed to by this link. Overrides<br />settings derived from property value it is decorating, if the value of the<br />property is ResourceLocation<Resource> |

### `@pollingOperation` {#@Azure.Core.pollingOperation}

Expand All @@ -289,7 +289,7 @@ Identifies that an operation is a polling operation for an LRO.
| Name | Type | Description |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| linkedOperation | `Operation` | The linked Operation |
| parameters | `model {}` | Map of `RequestParameter<Name>` and/or `ResponseProperty<Name>` that will<br />be passed to the linked operation request. |
| parameters | `{}` | Map of `RequestParameter<Name>` and/or `ResponseProperty<Name>` that will<br />be passed to the linked operation request. |

### `@pollingOperationParameter` {#@Azure.Core.pollingOperationParameter}

Expand All @@ -305,9 +305,9 @@ Used to define how to call custom polling operations for long-running operations

#### Parameters

| Name | Type | Description |
| --------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| targetParameter | `union ModelProperty \| string` | A reference to the polling operation parameter this parameter<br />provides a value for, or the name of that parameter. The default value is the name of<br />the decorated parameter or property. |
| Name | Type | Description |
| --------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| targetParameter | `ModelProperty \| string` | A reference to the polling operation parameter this parameter<br />provides a value for, or the name of that parameter. The default value is the name of<br />the decorated parameter or property. |

## Azure.Core.Foundations

Expand Down Expand Up @@ -341,9 +341,9 @@ Identifies a property on a request model that serves as a linked operation param

#### Parameters

| Name | Type | Description |
| ---- | ----------------------- | --------------------------- |
| name | `valueof scalar string` | Property name on the target |
| Name | Type | Description |
| ---- | ---------------- | --------------------------- |
| name | `valueof string` | Property name on the target |

### `@responseProperty` {#@Azure.Core.Foundations.responseProperty}

Expand All @@ -359,9 +359,9 @@ Identifies a property on _all_ non-error response models that serve as a linked

#### Parameters

| Name | Type | Description |
| ---- | ----------------------- | --------------------------- |
| name | `valueof scalar string` | Property name on the target |
| Name | Type | Description |
| ---- | ---------------- | --------------------------- |
| name | `valueof string` | Property name on the target |

## Azure.Core.Traits

Expand All @@ -377,13 +377,13 @@ checks.
#### Target

The model type to mark as a trait.
`(intrinsic) unknown`
`unknown`

#### Parameters

| Name | Type | Description |
| --------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
| traitName | `valueof scalar string` | An optional name to uniquely identify the trait. If unspecified,<br />the model type name is used. |
| Name | Type | Description |
| --------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| traitName | `valueof string` | An optional name to uniquely identify the trait. If unspecified,<br />the model type name is used. |

### `@traitAdded` {#@Azure.Core.Traits.traitAdded}

Expand All @@ -396,13 +396,13 @@ to either a trait model type or its envelope property.

#### Target

`union Model | ModelProperty`
`Model | ModelProperty`

#### Parameters

| Name | Type | Description |
| ------------ | -------------------------- | ------------------------------------------------- |
| addedVersion | `union EnumMember \| null` | The enum member representing the service version. |
| Name | Type | Description |
| ------------ | -------------------- | ------------------------------------------------- |
| addedVersion | `EnumMember \| null` | The enum member representing the service version. |

### `@traitContext` {#@Azure.Core.Traits.traitContext}

Expand All @@ -419,9 +419,9 @@ The trait envelope property where the context will be applied.

#### Parameters

| Name | Type | Description |
| -------- | -------------------------------------- | ------------------------------------------------------------------------------------------ |
| contexts | `union EnumMember \| Union \| unknown` | An enum member or union of enum members representing the trait's<br />applicable contexts. |
| Name | Type | Description |
| -------- | -------------------------------- | ------------------------------------------------------------------------------------------ |
| contexts | `EnumMember \| Union \| unknown` | An enum member or union of enum members representing the trait's<br />applicable contexts. |

### `@traitLocation` {#@Azure.Core.Traits.traitLocation}

Expand Down
14 changes: 7 additions & 7 deletions docs/libraries/azure-core/reference/interfaces.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ op Azure.Core.ResourceOperations.LongRunningResourceCreateOrReplace(apiVersion:
Create or update operation template.

```typespec
op Azure.Core.ResourceOperations.ResourceCreateOrUpdate(apiVersion: string, contentType: application/merge-patch+json, resource: Resource): (anonymous model) | (anonymous model) | ErrorResponse
op Azure.Core.ResourceOperations.ResourceCreateOrUpdate(apiVersion: string, contentType: "application/merge-patch+json", resource: Resource): (anonymous model) | (anonymous model) | ErrorResponse
```

##### Template Parameters
Expand All @@ -73,7 +73,7 @@ op Azure.Core.ResourceOperations.ResourceCreateOrUpdate(apiVersion: string, cont
Long-running resource create or update operation template.

```typespec
op Azure.Core.ResourceOperations.LongRunningResourceCreateOrUpdate(apiVersion: string, contentType: application/merge-patch+json, resource: Resource): (anonymous model) | (anonymous model) | ErrorResponse
op Azure.Core.ResourceOperations.LongRunningResourceCreateOrUpdate(apiVersion: string, contentType: "application/merge-patch+json", resource: Resource): (anonymous model) | (anonymous model) | ErrorResponse
```

##### Template Parameters
Expand All @@ -88,7 +88,7 @@ op Azure.Core.ResourceOperations.LongRunningResourceCreateOrUpdate(apiVersion: s
Resource update operation template.

```typespec
op Azure.Core.ResourceOperations.ResourceUpdate(apiVersion: string, contentType: application/merge-patch+json, resource: Resource): (anonymous model) | ErrorResponse
op Azure.Core.ResourceOperations.ResourceUpdate(apiVersion: string, contentType: "application/merge-patch+json", resource: Resource): (anonymous model) | ErrorResponse
```

##### Template Parameters
Expand Down Expand Up @@ -364,7 +364,7 @@ See https://azure.github.io/typespec-azure/docs/getstarted/azure-core/step05#def
Long-running operation signature to create or update a resource.

```typespec
op Azure.Core.LongRunningResourceCreateOrUpdate(apiVersion: string, contentType: application/merge-patch+json, resource: Resource): (anonymous model) | (anonymous model) | Azure.Core.Foundations.ErrorResponse
op Azure.Core.LongRunningResourceCreateOrUpdate(apiVersion: string, contentType: "application/merge-patch+json", resource: Resource): (anonymous model) | (anonymous model) | Azure.Core.Foundations.ErrorResponse
```

#### Template Parameters
Expand Down Expand Up @@ -502,7 +502,7 @@ See https://azure.github.io/typespec-azure/docs/getstarted/azure-core/step05#def
Operation signature to create or update a resource.

```typespec
op Azure.Core.ResourceCreateOrUpdate(apiVersion: string, contentType: application/merge-patch+json, resource: Resource): (anonymous model) | (anonymous model) | Azure.Core.Foundations.ErrorResponse
op Azure.Core.ResourceCreateOrUpdate(apiVersion: string, contentType: "application/merge-patch+json", resource: Resource): (anonymous model) | (anonymous model) | Azure.Core.Foundations.ErrorResponse
```

#### Template Parameters
Expand Down Expand Up @@ -596,7 +596,7 @@ See https://azure.github.io/typespec-azure/docs/getstarted/azure-core/step05#def
Operation signature to update a resource.

```typespec
op Azure.Core.ResourceUpdate(apiVersion: string, contentType: application/merge-patch+json, resource: Resource): (anonymous model) | Azure.Core.Foundations.ErrorResponse
op Azure.Core.ResourceUpdate(apiVersion: string, contentType: "application/merge-patch+json", resource: Resource): (anonymous model) | Azure.Core.Foundations.ErrorResponse
```

#### Template Parameters
Expand Down Expand Up @@ -666,7 +666,7 @@ op Azure.Core.Foundations.LongRunningOperation(apiVersion: string): Azure.Core.F
Long-running operation that updates a resource.

```typespec
op Azure.Core.Foundations.LongRunningResourceUpdate(apiVersion: string, contentType: application/merge-patch+json, resource: Resource): (anonymous model) | ErrorResponse
op Azure.Core.Foundations.LongRunningResourceUpdate(apiVersion: string, contentType: "application/merge-patch+json", resource: Resource): (anonymous model) | ErrorResponse
```

#### Template Parameters
Expand Down
Loading

0 comments on commit 8b79de7

Please sign in to comment.