Skip to content

Commit 5284104

Browse files
BernieWhiteBernieWhite
authored
Updates parameter descriptions for examples (#73)
1 parent 1902e28 commit 5284104

8 files changed

Lines changed: 116 additions & 122 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -74,15 +74,13 @@ For example:
7474
"storageAccountName": {
7575
"type": "string",
7676
"metadata": {
77-
"description": "Required. The name of the Storage Account."
77+
"description": "The name of the Storage Account."
7878
}
7979
},
8080
"tags": {
8181
"type": "object",
82-
"defaultValue": {
83-
},
8482
"metadata": {
85-
"description": "Optional. Tags to apply to the resource.",
83+
"description": "Tags to apply to the resource.",
8684
"example": {
8785
"service": "<service_name>",
8886
"env": "prod"
@@ -119,11 +117,11 @@ Generating documentation as markdown allows you to publish web-based content on
119117

120118
PSDocs supports the following metadata:
121119

122-
Field | Scope | Type | Description
123-
----- | ----- | ---- | -----------
124-
`name` | Template | `string` | Used for markdown page title.
125-
`summary` | Template | `string` | Used as a short description for the markdown page.
126-
`description` | Template | `string` | Used as a detailed description for the markdown page.
120+
Field | Scope | Type | Description
121+
----- | ----- | ---- | -----------
122+
`name` | Template | `string` | Used for markdown page title.
123+
`summary` | Template | `string` | Used as a short description for the markdown page.
124+
`description` | Template | `string` | Used as a detailed description for the markdown page.
127125
`description` | Parameter | `string` | Used as the description for the parameter.
128126
`example` | Parameter | `string`, `boolean`, `object`, or `array` | An example use of the parameter. The example is included in the JSON snippet. If an example is not included the default value is used instead.
129127
`ignore` | Parameter | `boolean` | When `true` the parameter is not included in the JSON snippet.

‎index.md‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -52,15 +52,13 @@ For example:
5252
"storageAccountName": {
5353
"type": "string",
5454
"metadata": {
55-
"description": "Required. The name of the Storage Account."
55+
"description": "The name of the Storage Account."
5656
}
5757
},
5858
"tags": {
5959
"type": "object",
60-
"defaultValue": {
61-
},
6260
"metadata": {
63-
"description": "Optional. Tags to apply to the resource.",
61+
"description": "Tags to apply to the resource.",
6462
"example": {
6563
"service": "<service_name>",
6664
"env": "prod"
@@ -87,11 +85,11 @@ Generating documentation as markdown allows you to publish web-based content on
8785

8886
PSDocs supports the following metadata:
8987

90-
Field | Scope | Type | Description
91-
----- | ----- | ---- | -----------
92-
`name` | Template | `string` | Used for markdown page title.
93-
`summary` | Template | `string` | Used as a short description for the markdown page.
94-
`description` | Template | `string` | Used as a detailed description for the markdown page.
88+
Field | Scope | Type | Description
89+
----- | ----- | ---- | -----------
90+
`name` | Template | `string` | Used for markdown page title.
91+
`summary` | Template | `string` | Used as a short description for the markdown page.
92+
`description` | Template | `string` | Used as a detailed description for the markdown page.
9593
`description` | Parameter | `string` | Used as the description for the parameter.
9694
`example` | Parameter | `string`, `boolean`, `object`, or `array` | An example use of the parameter. The example is included in the JSON snippet. If an example is not included the default value is used instead.
9795
`ignore` | Parameter | `boolean` | When `true` the parameter is not included in the JSON snippet.

‎templates/acr/v1/README.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,40 +8,40 @@ Create or update a Container Registry.
88

99
Parameter name | Required | Description
1010
-------------- | -------- | -----------
11-
registryName | Yes | Required. The name of the container registry.
12-
location | No | Optional. The location to deploy the container registry.
13-
registrySku | No | Optional. The container registry SKU.
14-
tags | No | Optional. Tags to apply to the resource.
11+
registryName | Yes | The name of the container registry.
12+
location | No | The location to deploy the container registry.
13+
registrySku | No | The container registry SKU.
14+
tags | Yes | Tags to apply to the resource.
1515

1616
### registryName
1717

1818
![Parameter Setting](https://img.shields.io/badge/parameter-required-orange?style=flat-square)
1919

20-
Required. The name of the container registry.
20+
The name of the container registry.
2121

2222
### location
2323

2424
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
2525

26-
Optional. The location to deploy the container registry.
26+
The location to deploy the container registry.
2727

2828
- Default value: `[resourceGroup().location]`
2929

3030
### registrySku
3131

3232
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
3333

34-
Optional. The container registry SKU.
34+
The container registry SKU.
3535

3636
- Default value: `Basic`
3737

3838
- Allowed values: `Basic`, `Standard`, `Premium`
3939

4040
### tags
4141

42-
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
42+
![Parameter Setting](https://img.shields.io/badge/parameter-required-orange?style=flat-square)
4343

44-
Optional. Tags to apply to the resource.
44+
Tags to apply to the resource.
4545

4646
## Snippets
4747

‎templates/acr/v1/template.json‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,16 @@
99
"registryName": {
1010
"type": "string",
1111
"metadata": {
12-
"description": "Required. The name of the container registry.",
12+
"description": "The name of the container registry.",
1313
"example": "<name>"
1414
}
1515
},
1616
"location": {
1717
"type": "string",
1818
"defaultValue": "[resourceGroup().location]",
1919
"metadata": {
20-
"description": "Optional. The location to deploy the container registry.",
21-
"example": "EastUS",
20+
"description": "The location to deploy the container registry.",
21+
"example": "eastus",
2222
"ignore": true
2323
}
2424
},
@@ -31,15 +31,13 @@
3131
"Premium"
3232
],
3333
"metadata": {
34-
"description": "Optional. The container registry SKU."
34+
"description": "The container registry SKU."
3535
}
3636
},
3737
"tags": {
38-
"type": "object",
39-
"defaultValue": {
40-
},
38+
"type": "object",
4139
"metadata": {
42-
"description": "Optional. Tags to apply to the resource.",
40+
"description": "Tags to apply to the resource.",
4341
"example": {
4442
"service": "<service_name>",
4543
"env": "prod"

‎templates/keyvault/v1/README.md‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -8,103 +8,103 @@ Create or update a Key Vault.
88

99
Parameter name | Required | Description
1010
-------------- | -------- | -----------
11-
vaultName | Yes | Required. The name of the Key Vault.
12-
location | No | Optional. The Azure region to deploy to.
13-
accessPolicies | No | Optional. The access policies defined for this vault.
14-
useDeployment | No | Optional. Determines if Azure can deploy certificates from this Key Vault.
15-
useTemplate | No | Optional. Determines if templates can reference secrets from this Key Vault.
16-
useDiskEncryption | No | Optional. Determines if this Key Vault can be used for Azure Disk Encryption.
17-
useSoftDelete | No | Optional. Determine if soft delete is enabled on this Key Vault.
18-
usePurgeProtection | No | Optional. Determine if purge protection is enabled on this Key Vault.
19-
networkAcls | No | Optional. The network firewall defined for this vault.
20-
workspaceId | No | Optional. The workspace to store audit logs.
21-
tags | No | Optional. Tags to apply to the resource.
11+
vaultName | Yes | The name of the Key Vault.
12+
location | No | The Azure region to deploy to.
13+
accessPolicies | No | The access policies defined for this vault.
14+
useDeployment | No | Determines if Azure can deploy certificates from this Key Vault.
15+
useTemplate | No | Determines if templates can reference secrets from this Key Vault.
16+
useDiskEncryption | No | Determines if this Key Vault can be used for Azure Disk Encryption.
17+
useSoftDelete | No | Determine if soft delete is enabled on this Key Vault.
18+
usePurgeProtection | No | Determine if purge protection is enabled on this Key Vault.
19+
networkAcls | No | The network firewall defined for this vault.
20+
workspaceId | No | The workspace to store audit logs.
21+
tags | Yes | Tags to apply to the resource.
2222

2323
### vaultName
2424

2525
![Parameter Setting](https://img.shields.io/badge/parameter-required-orange?style=flat-square)
2626

27-
Required. The name of the Key Vault.
27+
The name of the Key Vault.
2828

2929
### location
3030

3131
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
3232

33-
Optional. The Azure region to deploy to.
33+
The Azure region to deploy to.
3434

3535
- Default value: `[resourceGroup().location]`
3636

3737
### accessPolicies
3838

3939
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
4040

41-
Optional. The access policies defined for this vault.
41+
The access policies defined for this vault.
4242

4343
### useDeployment
4444

4545
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
4646

47-
Optional. Determines if Azure can deploy certificates from this Key Vault.
47+
Determines if Azure can deploy certificates from this Key Vault.
4848

4949
- Default value: `False`
5050

5151
### useTemplate
5252

5353
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
5454

55-
Optional. Determines if templates can reference secrets from this Key Vault.
55+
Determines if templates can reference secrets from this Key Vault.
5656

5757
- Default value: `False`
5858

5959
### useDiskEncryption
6060

6161
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
6262

63-
Optional. Determines if this Key Vault can be used for Azure Disk Encryption.
63+
Determines if this Key Vault can be used for Azure Disk Encryption.
6464

6565
- Default value: `False`
6666

6767
### useSoftDelete
6868

6969
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
7070

71-
Optional. Determine if soft delete is enabled on this Key Vault.
71+
Determine if soft delete is enabled on this Key Vault.
7272

7373
- Default value: `True`
7474

7575
### usePurgeProtection
7676

7777
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
7878

79-
Optional. Determine if purge protection is enabled on this Key Vault.
79+
Determine if purge protection is enabled on this Key Vault.
8080

8181
- Default value: `True`
8282

8383
### networkAcls
8484

8585
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
8686

87-
Optional. The network firewall defined for this vault.
87+
The network firewall defined for this vault.
8888

8989
- Default value: `@{defaultAction=Allow; bypass=AzureServices; ipRules=System.Object[]; virtualNetworkRules=System.Object[]}`
9090

9191
### workspaceId
9292

9393
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
9494

95-
Optional. The workspace to store audit logs.
95+
The workspace to store audit logs.
9696

9797
### tags
9898

99-
![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
99+
![Parameter Setting](https://img.shields.io/badge/parameter-required-orange?style=flat-square)
100100

101-
Optional. Tags to apply to the resource.
101+
Tags to apply to the resource.
102102

103103
## Outputs
104104

105105
Name | Type | Description
106106
---- | ---- | -----------
107-
resourceId | string |
107+
resourceId | string | A unique resource identifier for the Key Vault.
108108

109109
## Snippets
110110

‎templates/keyvault/v1/template.json‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -9,24 +9,24 @@
99
"vaultName": {
1010
"type": "string",
1111
"metadata": {
12-
"description": "Required. The name of the Key Vault.",
12+
"description": "The name of the Key Vault.",
1313
"example": "<name>"
1414
}
1515
},
1616
"location": {
1717
"type": "string",
1818
"defaultValue": "[resourceGroup().location]",
1919
"metadata": {
20-
"description": "Optional. The Azure region to deploy to.",
21-
"example": "EastUS",
20+
"description": "The Azure region to deploy to.",
21+
"example": "eastus",
2222
"ignore": true
2323
}
2424
},
2525
"accessPolicies": {
2626
"type": "array",
2727
"defaultValue": [],
2828
"metadata": {
29-
"description": "Optional. The access policies defined for this vault.",
29+
"description": "The access policies defined for this vault.",
3030
"example": [
3131
{
3232
"objectId": "<object_id>",
@@ -46,36 +46,36 @@
4646
"type": "bool",
4747
"defaultValue": false,
4848
"metadata": {
49-
"description": "Optional. Determines if Azure can deploy certificates from this Key Vault."
49+
"description": "Determines if Azure can deploy certificates from this Key Vault."
5050
}
5151
},
5252
"useTemplate": {
5353
"type": "bool",
5454
"defaultValue": false,
5555
"metadata": {
56-
"description": "Optional. Determines if templates can reference secrets from this Key Vault."
56+
"description": "Determines if templates can reference secrets from this Key Vault."
5757
}
5858
},
5959
"useDiskEncryption": {
6060
"type": "bool",
6161
"defaultValue": false,
6262
"metadata": {
63-
"description": "Optional. Determines if this Key Vault can be used for Azure Disk Encryption."
63+
"description": "Determines if this Key Vault can be used for Azure Disk Encryption."
6464
}
6565
},
6666
"useSoftDelete": {
6767
"type": "bool",
6868
"defaultValue": true,
6969
"metadata": {
70-
"description": "Optional. Determine if soft delete is enabled on this Key Vault.",
70+
"description": "Determine if soft delete is enabled on this Key Vault.",
7171
"ignore": true
7272
}
7373
},
7474
"usePurgeProtection": {
7575
"type": "bool",
7676
"defaultValue": true,
7777
"metadata": {
78-
"description": "Optional. Determine if purge protection is enabled on this Key Vault.",
78+
"description": "Determine if purge protection is enabled on this Key Vault.",
7979
"ignore": true
8080
}
8181
},
@@ -88,22 +88,21 @@
8888
"virtualNetworkRules": []
8989
},
9090
"metadata": {
91-
"description": "Optional. The network firewall defined for this vault."
91+
"description": "The network firewall defined for this vault."
9292
}
9393
},
9494
"workspaceId": {
9595
"type": "string",
9696
"defaultValue": "",
9797
"metadata": {
98-
"description": "Optional. The workspace to store audit logs.",
98+
"description": "The workspace to store audit logs.",
9999
"example": "<resource_id>"
100100
}
101101
},
102102
"tags": {
103103
"type": "object",
104-
"defaultValue": {},
105104
"metadata": {
106-
"description": "Optional. Tags to apply to the resource.",
105+
"description": "Tags to apply to the resource.",
107106
"example": {
108107
"service": "<service_name>",
109108
"env": "prod"
@@ -161,7 +160,10 @@
161160
"outputs": {
162161
"resourceId": {
163162
"type": "string",
164-
"value": "[resourceId('Microsoft.KeyVault/vaults', parameters('vaultName'))]"
163+
"value": "[resourceId('Microsoft.KeyVault/vaults', parameters('vaultName'))]",
164+
"metadata": {
165+
"description": "A unique resource identifier for the Key Vault."
166+
}
165167
}
166168
}
167169
}

0 commit comments

Comments
 (0)