update

Author: mumian

articles/azure-resource-manager/bicep/bicep-import.md

@@ -43,7 +43,7 @@ import * as <alias_name> from '<bicep_file_name>'
 
 You can mix and match the preceding syntaxes. To access imported symbols using the wildcard syntax, you must use the `.` operator: `<alias_name>.<exported_symbol>`.
 
-Only statements that have been [exported](#exporting-types-variables-and-functions) in the file being referenced are available to be imported.
+Only statements that have been [exported](#export-variables-types-and-functions) in the file being referenced are available to be imported.
 
 Functionality that has been imported from another file can be used without restrictions. For example, imported variables can be used anywhere a variable declared in-file would normally be valid.
 

articles/azure-resource-manager/bicep/data-types.md

@@ -385,7 +385,7 @@ The union type syntax can be used in [user-defined data types](./user-defined-da
 
 ## Secure strings and objects
 
-Secure string uses the same format as string, and secure object uses the same format as object. With Bicep, you add the `@secure()` [decorator](./parameters.md#decorators) to a string or object.
+Secure string uses the same format as string, and secure object uses the same format as object. With Bicep, you add the `@secure()` [decorator](./parameters.md#use-decorators) to a string or object.
 
 When you set a parameter to a secure string or secure object, the value of the parameter isn't saved to the deployment history and isn't logged. However, if you set that secure value to a property that isn't expecting a secure value, the value isn't protected. For example, if you set a secure string to a tag, that value is stored as plain text. Use secure strings for passwords and secrets.
 

articles/azure-resource-manager/bicep/file.md

@@ -118,18 +118,18 @@ You can add one or more decorators for each of the following element.
 
 | Decorator | Apply to element | Apply to data type | Argument | Description |
 | --------- | ---- | ----------- | ------- |
-| [allowed](#allowed-values) | parameter | all | array | Use this decorator to make sure the user provides correct values. This decorator is only permitted on `param` statements. To declare that a property must be one of a set of predefined values in a [`type`](./user-defined-data-types.md) or [`output`](./outputs.md) statement, use [union type syntax](./data-types.md#union-types). Union type syntax can also be used in `param` statements.|
-| [batch]() |resource, module||||
-| [description](#description) | parameter, variable  | all | string | Text that explains how to use the parameter. The description is displayed to users through the portal. |
-| [discriminator](#property-name) | parameters | object | string | Use this decorator to ensure the correct subclass is identified and managed. For more information, see [Custom-tagged union data type](./data-types.md#custom-tagged-union-data-type).|
-| [export]() | variable, type, function ||||
-| [maxLength](#length-constraints) | parameter | array, string | int | The maximum length for string and array parameters. The value is inclusive. |
-| [maxValue](#integer-constraints) | parameter | int | int | The maximum value for the integer parameter. This value is inclusive. |
-| [metadata](#metadata) | parameter | all | object | Custom properties to apply to the parameter. Can include a description property that is equivalent to the description decorator. |
-| [minLength](#length-constraints) | parameter | array, string | int | The minimum length for string and array parameters. The value is inclusive. |
-| [minValue](#integer-constraints) | parameter | int | int | The minimum value for the integer parameter. This value is inclusive. |
-| [sealed](#sealed) | parameter, type, output | object | none | Elevate [BCP089](./diagnostics/bcp089.md) from a warning to an error when a property name of a use-define data type is likely a typo. For more information, see [](./user-defined-data-types.md#elevate-error-level). |
-| [secure](#secure-parameters) | parameter | string, object | none | Marks the parameter as secure. The value for a secure parameter isn't saved to the deployment history and isn't logged. For more information, see [Secure strings and objects](data-types.md#secure-strings-and-objects). |
+| allowed | parameter | all | array | Use this decorator to make sure the user provides correct values. This decorator is only permitted on `param` statements. To declare that a property must be one of a set of predefined values in a [`type`](./user-defined-data-types.md) or [`output`](./outputs.md) statement, use [union type syntax](./data-types.md#union-types). Union type syntax can also be used in `param` statements.|
+| batch |resource, module||||
+| description | parameter, variable  | all | string | Text that explains how to use the parameter. The description is displayed to users through the portal. |
+| discriminator | parameters | object | string | Use this decorator to ensure the correct subclass is identified and managed. For more information, see [Custom-tagged union data type](./data-types.md#custom-tagged-union-data-type).|
+| export | variable, type, function ||||
+| maxLength | parameter | array, string | int | The maximum length for string and array parameters. The value is inclusive. |
+| maxValue | parameter | int | int | The maximum value for the integer parameter. This value is inclusive. |
+| metadata | parameter | all | object | Custom properties to apply to the parameter. Can include a description property that is equivalent to the description decorator. |
+| minLength | parameter | array, string | int | The minimum length for string and array parameters. The value is inclusive. |
+| minValue | parameter | int | int | The minimum value for the integer parameter. This value is inclusive. |
+| sealed | parameter, type, output | object | none | Elevate [BCP089](./diagnostics/bcp089.md) from a warning to an error when a property name of a use-define data type is likely a typo. For more information, see [Elevate error level](./user-defined-data-types.md#elevate-error-level). |
+| secure | parameter | string, object | none | Marks the parameter as secure. The value for a secure parameter isn't saved to the deployment history and isn't logged. For more information, see [Secure strings and objects](data-types.md#secure-strings-and-objects). |
 
 ## Parameters
 
@@ -149,7 +149,7 @@ sku: {
 }
 ```
 
-You can add one or more decorators for each parameter. For more information, see [Decorators](./parameters.md#use-decorators).
+You can add one or more decorators for each parameter. For more information, see [Use decorators](./parameters.md#use-decorators).
 
 For more information, see [Parameters in Bicep](./parameters.md).
 
@@ -168,7 +168,7 @@ resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
   name: uniqueStorageName
 ```
 
-You can add one or more decorators for each variable. For more information, see [Decorators](./variables.md#use-decorators).
+You can add one or more decorators for each variable. For more information, see [Use decorators](./variables.md#use-decorators).
 
 For more information, see [Variables in Bicep](./variables.md).
 
@@ -201,7 +201,7 @@ resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
 }
 ```
 
-You can add one or more decorators for each user-defined data type. For more information, see [Decorators](./user-defined-data-types.md#use-decorators).
+You can add one or more decorators for each user-defined data type. For more information, see [Use decorators](./user-defined-data-types.md#use-decorators).
 
 For more information, see [User-defined data types](./user-defined-data-types.md).
 
@@ -215,8 +215,6 @@ func buildUrl(https bool, hostname string, path string) string => '${https ? 'ht
 output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')
 ```
 
-You can add one or more decorators for each user-defined function. For more information, see [Decorators](./user-defined-functions.md#use-decorators).
-
 For more information, see [User-defined functions](./user-defined-functions.md).
 
 ## Resources
@@ -239,7 +237,7 @@ resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
 }
 ```
 
-You can add one or more decorators for each resource. For more information, see [Decorators](./resource-declaration.md#use-decorators).
+You can add one or more decorators for each resource. For more information, see [Use decorators](./resource-declaration.md#use-decorators).
 
 For more information, see [Resource declaration in Bicep](resource-declaration.md).
 
@@ -307,7 +305,7 @@ module webModule './webApp.bicep' = {
 
 The symbolic name enables you to reference the module from somewhere else in the file. For example, you can get an output value from a module by using the symbolic name and the name of the output value.
 
-You can add one or more decorators for each module. For more information, see [Decorators](./modules.md#use-decorators).
+You can add one or more decorators for each module. For more information, see [Use decorators](./modules.md#use-decorators).
 
 For more information, see [Use Bicep modules](./modules.md).
 
@@ -319,7 +317,7 @@ Use outputs to return values from the deployment. Typically, you return a value
 output storageEndpoint object = stg.properties.primaryEndpoints
 ```
 
-You can add one or more decorators for each output. For more information, see [Decorators](./outputs.md#use-decorators).
+You can add one or more decorators for each output. For more information, see [Use decorators](./outputs.md#use-decorators).
 
 For more information, see [Outputs in Bicep](./outputs.md).
 

articles/azure-resource-manager/bicep/modules.md

@@ -268,6 +268,49 @@ module stgModule 'ts/ContosoSpecs:storageSpec:2.0' = {
 }
 ```
 
+## Use decorators
+
+Decorators are written in the format `@expression` and are placed above module declarations. The following table shows the available decorators for modules.
+
+| Decorator | Argument | Description |
+| --------- | ----------- | ------- |
+| [description](#description) | string | Text that explains how to use the variable.|
+| [batchSize](./bicep-import.md#export-variables-types-and-functions) | none | Indicates that the variable can be imported by another file. |
+
+Decorators are in the [sys namespace](bicep-functions.md#namespaces-for-functions). If you need to differentiate a decorator from another item with the same name, preface the decorator with `sys`. For example, if your Bicep file includes a parameter named `description`, you must add the sys namespace when using the **description** decorator.
+
+### Description
+
+To add explaination, add a description to module declarations. For example:
+
+```bicep
+@description('Create storage accounts referencing an AVM.')
+module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
+  name: 'myStorage'
+  params: {
+    name: 'store${resourceGroup().name}'
+  }
+}
+```
+
+### BatchSize
+
+You can only apply `@batchSize()` to a resource or module definition that uses a [`for` expression](./loops.md).
+
+By default, modules are deployed in parallel. When you add the `@batchSize(int)` decorator, you deploy instances serially.
+
+```bicep
+@batchSize(3)
+module storage 'br/public:avm/res/storage/storage-account:0.11.1' = [for storageName in storageAccounts: {
+  name: 'myStorage'
+  params: {
+    name: 'store${resourceGroup().name}'
+  }
+}]
+```
+
+For more information, see [Deploy in batches](loops.md#deploy-in-batches).
+
 ## Parameters
 
 The parameters you provide in your module definition match the parameters in the Bicep file.

articles/azure-resource-manager/bicep/outputs.md

@@ -56,6 +56,8 @@ output out 'a' | 'b' = foo
 
 For more information, see [User-defined data types](./user-defined-data-types.md).
 
+## Use decorators
+
 ## Conditional output
 
 When the value to return depends on a condition in the deployment, use the `?` operator.

articles/azure-resource-manager/bicep/parameters.md

@@ -89,31 +89,19 @@ However, you can't reference a [variable](./variables.md) as the default value.
 
 ## Use decorators
 
-Parameters use decorators for constraints or metadata. The decorators are in the format `@expression` and are placed above the parameter's declaration. You can mark a parameter as secure, specify allowed values, set the minimum and maximum length for a string, set the minimum and maximum value for an integer, and provide a description of the parameter.
-
-The following example shows two common uses for decorators.
-
-```bicep
-@secure()
-param demoPassword string
-
-@description('Must be at least Standard_A3 to support 2 NICs.')
-param virtualMachineSize string = 'Standard_DS1_v2'
-```
-
-The following table describes the available decorators and how to use them.
+Parameters use decorators for constraints or metadata. The decorators are in the format `@expression` and are placed above the parameter's declaration. The following table shows the available decorators for parameters.
 
 | Decorator | Apply to | Argument | Description |
 | --------- | ---- | ----------- | ------- |
 | [allowed](#allowed-values) | all | array | Use this decorator to make sure the user provides correct values. This decorator is only permitted on `param` statements. To declare that a property must be one of a set of predefined values in a [`type`](./user-defined-data-types.md) or [`output`](./outputs.md) statement, use [union type syntax](./data-types.md#union-types). Union type syntax can also be used in `param` statements.|
 | [description](#description) | all | string | Text that explains how to use the parameter. The description is displayed to users through the portal. |
-| [discriminator](#property-name) | object | string | Use this decorator to ensure the correct subclass is identified and managed. For more information, see [Custom-tagged union data type](./data-types.md#custom-tagged-union-data-type).|
+| [discriminator](#discriminator) | object | string | Use this decorator to ensure the correct subclass is identified and managed. For more information, see [Custom-tagged union data type](./data-types.md#custom-tagged-union-data-type).|
 | [maxLength](#length-constraints) | array, string | int | The maximum length for string and array parameters. The value is inclusive. |
 | [maxValue](#integer-constraints) | int | int | The maximum value for the integer parameter. This value is inclusive. |
 | [metadata](#metadata) | all | object | Custom properties to apply to the parameter. Can include a description property that is equivalent to the description decorator. |
 | [minLength](#length-constraints) | array, string | int | The minimum length for string and array parameters. The value is inclusive. |
 | [minValue](#integer-constraints) | int | int | The minimum value for the integer parameter. This value is inclusive. |
-| [sealed](#sealed) | object | none | Elevate [BCP089](./diagnostics/bcp089.md) from a warning to an error when a property name of a use-define data type is likely a typo. For more information, see [](./user-defined-data-types.md#elevate-error-level). |
+| [sealed](#sealed) | object | none | Elevate [BCP089](./diagnostics/bcp089.md) from a warning to an error when a property name of a use-define data type is likely a typo. For more information, see [Elevate error level](./user-defined-data-types.md#elevate-error-level). |
 | [secure](#secure-parameters) | string, object | none | Marks the parameter as secure. The value for a secure parameter isn't saved to the deployment history and isn't logged. For more information, see [Secure strings and objects](data-types.md#secure-strings-and-objects). |
 
 Decorators are in the [sys namespace](bicep-functions.md#namespaces-for-functions). If you need to differentiate a decorator from another item with the same name, preface the decorator with `sys`. For example, if your Bicep file includes a parameter named `description`, you must add the sys namespace when using the **description** decorator.
@@ -125,8 +113,6 @@ param name string
 param description string
 ```
 
-The available decorators are described in the following sections.
-
 ### Allowed values
 
 You can define allowed values for a parameter. You provide the allowed values in an array. The deployment fails during validation if a value is passed in for the parameter that isn't one of the allowed values.
@@ -232,6 +218,8 @@ param demoPassword string
 param demoSecretObject object
 ```
 
+There are several linter rules related to this decorator: [Secure parameter default](./linter-rule-secure-parameter-default.md), [Secure parameters in nested deployments](./linter-rule-secure-params-in-nested-deploy.md), [Secure secrets in parameters](./linter-rule-secure-secrets-in-parameters.md).
+
 ## Use parameters
 
 To reference the value for a parameter, use the parameter name. The following example uses a parameter value for a key vault name.

articles/azure-resource-manager/bicep/resource-declaration.md

@@ -60,54 +60,42 @@ resource <symbolic-name> '<full-type-name>@<api-version>' = {
 }
 ```
 
-## Decorators
+## Use decorators
 
+Decorators are written in the format `@expression` and are placed above resource declarations. The following table shows the available decorators for resources.
 
+| Decorator | Argument | Description |
+| --------- | ----------- | ------- |
+| [description](#description) | string | Text that explains how to use the variable.|
+| [batchSize](./bicep-import.md#export-variables-types-and-functions) | none | Indicates that the variable can be imported by another file. |
 
-## Resource and module decorators
+Decorators are in the [sys namespace](bicep-functions.md#namespaces-for-functions). If you need to differentiate a decorator from another item with the same name, preface the decorator with `sys`. For example, if your Bicep file includes a parameter named `description`, you must add the sys namespace when using the **description** decorator.
 
-You can add a decorator to a resource or module definition. The supported decorators are `batchSize(int)` and `description`. You can only apply it to a resource or module definition that uses a `for` expression.
+### Description
 
-By default, resources are deployed in parallel. When you add the `batchSize(int)` decorator, you deploy instances serially.
+To add explaination, add a description to resource declarations. For example:
 
 ```bicep
-@batchSize(3)
+@description('Create a number of storage accounts')
 resource storageAccountResources 'Microsoft.Storage/storageAccounts@2023-04-01' = [for storageName in storageAccounts: {
   ...
 }]
 ```
 
-For more information, see [Deploy in batches](loops.md#deploy-in-batches).
-
-
-
-
-
+### BatchSize
 
+You can only apply `@batchSize()` to a resource or module definition that uses a [`for` expression](./loops.md).
 
-
-
-
-The following table describes the available decorators and how to use them.
-
-| Decorator | Argument | Description |
-| --------- | ----------- | ------- |
-| [description](#description) | string | Text that explains how to use the variable.|
-| [batchSize](./bicep-import.md#export-variables-types-and-functions) | none | Indicates that the variable can be imported by another file. |
-
-Decorators are in the [sys namespace](bicep-functions.md#namespaces-for-functions). If you need to differentiate a decorator from another item with the same name, preface the decorator with `sys`. For example, if your Bicep file includes a parameter named `description`, you must add the sys namespace when using the **description** decorator.
-
-You can add a decorator to a resource definition. The supported decorators are `@batchSize(int)` and `@description`. 
+By default, resources are deployed in parallel. When you add the `batchSize(int)` decorator, you deploy instances serially.
 
 ```bicep
-@description('Create a number of storage accounts')
 @batchSize(3)
 resource storageAccountResources 'Microsoft.Storage/storageAccounts@2023-04-01' = [for storageName in storageAccounts: {
   ...
 }]
 ```
 
-You can only apply the `@batchSize()` decorator to a resource or module definition that uses a `for` expression. For more information, see [Deploy in batches](loops.md#deploy-in-batches).
+For more information, see [Deploy in batches](loops.md#deploy-in-batches).
 
 ## Resource name