Merge pull request #285062 from mumian/0812-bicep-export

Refresh and restructure the Decorator content

Author: Jill Grant

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

@@ -3,16 +3,16 @@ title: Imports in Bicep
 description: Describes how to import shared functionality and namespaces in Bicep.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 08/07/2024
+ms.date: 08/20/2024
 ---
 
 # Imports in Bicep
 
-This article describes the syntax you use to export and import shared functionality, as well as namespaces for Bicep extensions.
+This article describes the syntax you use to export and import shared functionality, and namespaces for Bicep extensions.
 
-## Exporting types, variables and functions
+## Export variables, types, and functions
 
-The `@export()` decorator indicates that a given statement can be imported by another file. This decorator is only valid on type, variable, and function statements. Variable statements marked with `@export()` must be compile-time constants.
+The `@export()` decorator indicates that a given statement can be imported by another file. This decorator is only valid on [`type`](./user-defined-data-types.md), [`var`](./variables.md), and [`func`](./user-defined-functions.md) statements. Variable statements marked with `@export()` must be compile-time constants.
 
 The syntax for exporting functionality for use in other Bicep files is:
 
@@ -21,7 +21,7 @@ The syntax for exporting functionality for use in other Bicep files is:
 <statement_to_export>
 ```
 
-## Import types, variables, and functions
+## Import variables, types, and functions
 
 The syntax for importing functionality from another Bicep file is:
 
@@ -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

@@ -3,7 +3,7 @@ title: Data types in Bicep
 description: Describes the data types that are available in Bicep
 ms.topic: reference
 ms.custom: devx-track-bicep
-ms.date: 07/16/2024
+ms.date: 08/20/2024
 ---
 
 # Data types in Bicep
@@ -319,7 +319,7 @@ is ${blocked}'''
 
 ## Union types
 
-In Bicep, a union type allows the creation of a combined type consisting of a set of sub-types. An assignment is valid if any of the individual sub-type assignments are permitted. The `|` character separates individual sub-types using an _or_ condition. For example, the syntax _'a' | 'b'_ means that a valid assignment could be either _'a'_ or _'b'_. Union types are translated into the [allowed-value](../templates/definitions.md#allowed-values) constraint in Bicep, so only literals are permitted as members. Unions can include any number of literal-typed expressions.
+In Bicep, a union type allows the creation of a combined type consisting of a set of subtypes. An assignment is valid if any of the individual subtype assignments are permitted. The `|` character separates individual subtypes using an _or_ condition. For example, the syntax _'a' | 'b'_ means that a valid assignment could be either _'a'_ or _'b'_. Union types are translated into the [allowed-value](../templates/definitions.md#allowed-values) constraint in Bicep, so only literals are permitted as members. Unions can include any number of literal-typed expressions.
 
 ```bicep
 type color = 'Red' | 'Blue' | 'White'
@@ -335,7 +335,7 @@ Type unions must be reducible to a single ARM type, such as 'string', 'int', or
 type foo = 'a' | 1
 ```
 
-Any type expression can be used as a sub-type in a union type declaration (between `|` characters). For example, the following examples are all valid:
+Any type expression can be used as a subtype in a union type declaration (between `|` characters). For example, the following examples are all valid:
 
 ```bicep
 type foo = 1 | 2
@@ -379,13 +379,13 @@ There are some limitations with union type.
   ```
 
 * Only literals are permitted as members.
-* All literals must be of the same primitive data type (e.g., all strings or all integers).
+* All literals must be of the same primitive data type (for example, all strings or all integers).
 
 The union type syntax can be used in [user-defined data types](./user-defined-data-types.md).
 
 ## 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

@@ -3,7 +3,7 @@ title: Bicep file structure and syntax
 description: Describes the structure and properties of a Bicep file using declarative syntax.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 07/11/2024
+ms.date: 08/20/2024
 ---
 
 # Understand the structure and syntax of Bicep files
@@ -23,19 +23,24 @@ metadata <metadata-name> = ANY
 
 targetScope = '<scope>'
 
+@<decorator>(<argument>)
 type <user-defined-data-type-name> = <type-expression>
 
+@<decorator>(<argument>)
 func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>
 
 @<decorator>(<argument>)
 param <parameter-name> <parameter-data-type> = <default-value>
 
+@<decorator>(<argument>)
 var <variable-name> = <variable-value>
 
+@<decorator>(<argument>)
 resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
   <resource-properties>
 }
 
+@<decorator>(<argument>)
 module <module-symbolic-name> '<path-to-file>' = {
   name: '<linked-deployment-name>'
   params: {
@@ -99,6 +104,74 @@ The allowed values are:
 
 In a module, you can specify a scope that is different than the scope for the rest of the Bicep file. For more information, see [Configure module scope](modules.md#set-module-scope)
 
+## Decorators
+
+You can add one or more decorators for each of the following elements:
+
+* [param](#parameters)
+* [var](#variables)
+* [resource](#resources)
+* [module](#modules)
+* [output](#outputs)
+* [func](#functions)
+* [type](#types)
+
+| Decorator | Apply to element | Apply to data type | Argument | Description |
+| --------- | ---- | ----------- | ------- |
+| allowed | [param](./parameters.md#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.|
+| batchSize |[resource](./resource-declaration.md#batchsize), [module](./modules.md#batchsize)| N/A | integer | Set up instances to deploy sequentially. |
+| description | [param](./parameters.md#description), [var](./variables.md#description), [resource](./resource-declaration.md#description), [module](./modules.md#description), [output](./outputs.md#description), [type](./user-defined-data-types.md#description), [func](./user-defined-functions.md#description) | all | string | Provide descriptions for the elements. Markdown-formatted text can be used for the description text. |
+| discriminator | [param](./parameters.md#discriminator), [type](./user-defined-data-types.md#discriminator), [output](./outputs.md#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).|
+| export | [var](./variables.md#export), [type](./user-defined-data-types.md#export), [func](./user-defined-functions.md#export) | all | none| Indicates that the element can be imported by another Bicep file. |
+| maxLength | [param](./parameters.md#length-constraints), [output](./outputs.md#length-constraints) | array, string | int | The maximum length for string and array elements. The value is inclusive. |
+| maxValue | [param](./parameters.md#integer-constraints), [output](./outputs.md#integer-constraints) | int | int | The maximum value for the integer elements. This value is inclusive. |
+| metadata | [param](./parameters.md#metadata), [output](./outputs.md#metadata) | all | object | Custom properties to apply to the elements. Can include a description property that is equivalent to the description decorator. |
+| minLength | [param](./parameters.md#length-constraints), [output](./outputs.md#length-constraints) | array, string | int | The minimum length for string and array elements. The value is inclusive. |
+| minValue | [param](./parameters.md#integer-constraints), [output](./outputs.md#integer-constraints) | int | int | The minimum value for the integer elements. This value is inclusive. |
+| sealed | [param](./parameters.md#sealed), [type](./user-defined-data-types.md#sealed), [output](./outputs.md#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 | [param](./parameters.md#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). |
+
+## Parameters
+
+Use parameters for values that need to vary for different deployments. You can define a default value for the parameter that is used if no value is provided during deployment.
+
+For example, you can add a SKU parameter to specify different sizes for a resource. You might pass in different values depending on whether you're deploying to test or production.
+
+```bicep
+param storageSKU string = 'Standard_LRS'
+```
+
+The parameter is available for use in your Bicep file.
+
+```bicep
+sku: {
+  name: storageSKU
+}
+```
+
+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).
+
+## Variables
+
+You can make your Bicep file more readable by encapsulating complex expressions in a variable. For example, you might add a variable for a resource name that is constructed by concatenating several values together.
+
+```bicep
+var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'
+```
+
+Apply this variable wherever you need the complex expression.
+
+```bicep
+resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
+  name: uniqueStorageName
+```
+
+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).
+
 ## Types
 
 You can use the `type` statement to define user-defined data types.
@@ -128,6 +201,8 @@ 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 [Use decorators](./user-defined-data-types.md#use-decorators).
+
 For more information, see [User-defined data types](./user-defined-data-types.md).
 
 ## Functions
@@ -142,59 +217,6 @@ output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')
 
 For more information, see [User-defined functions](./user-defined-functions.md).
 
-## Parameters
-
-Use parameters for values that need to vary for different deployments. You can define a default value for the parameter that is used if no value is provided during deployment.
-
-For example, you can add a SKU parameter to specify different sizes for a resource. You might pass in different values depending on whether you're deploying to test or production.
-
-```bicep
-param storageSKU string = 'Standard_LRS'
-```
-
-The parameter is available for use in your Bicep file.
-
-```bicep
-sku: {
-  name: storageSKU
-}
-```
-
-For more information, see [Parameters in Bicep](./parameters.md).
-
-## Parameter decorators
-
-You can add one or more decorators for each parameter. These decorators describe the parameter and define constraints for the values that are passed in. The following example shows one decorator but many others are available.
-
-```bicep
-@allowed([
-  'Standard_LRS'
-  'Standard_GRS'
-  'Standard_ZRS'
-  'Premium_LRS'
-])
-param storageSKU string = 'Standard_LRS'
-```
-
-For more information, including descriptions of all available decorators, see [Decorators](parameters.md#decorators).
-
-## Variables
-
-You can make your Bicep file more readable by encapsulating complex expressions in a variable. For example, you might add a variable for a resource name that is constructed by concatenating several values together.
-
-```bicep
-var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'
-```
-
-Apply this variable wherever you need the complex expression.
-
-```bicep
-resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
-  name: uniqueStorageName
-```
-
-For more information, see [Variables in Bicep](./variables.md).
-
 ## Resources
 
 Use the `resource` keyword to define a resource to deploy. Your resource declaration includes a symbolic name for the resource. You use this symbolic name in other parts of the Bicep file to get a value from the resource.
@@ -215,6 +237,8 @@ resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
 }
 ```
 
+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).
 
 Some resources have a parent/child relationship. You can define a child resource either inside the parent resource or outside of it.
@@ -281,22 +305,9 @@ 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.
 
-For more information, see [Use Bicep modules](./modules.md).
-
-## Resource and module decorators
-
-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.
-
-By default, resources are deployed in parallel. When you add the `batchSize(int)` decorator, you deploy instances serially.
-
-```bicep
-@batchSize(3)
-resource storageAccountResources 'Microsoft.Storage/storageAccounts@2023-04-01' = [for storageName in storageAccounts: {
-  ...
-}]
-```
+You can add one or more decorators for each module. For more information, see [Use decorators](./modules.md#use-decorators).
 
-For more information, see [Deploy in batches](loops.md#deploy-in-batches).
+For more information, see [Use Bicep modules](./modules.md).
 
 ## Outputs
 
@@ -306,6 +317,8 @@ 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 [Use decorators](./outputs.md#use-decorators).
+
 For more information, see [Outputs in Bicep](./outputs.md).
 
 ## Loops
@@ -423,7 +436,7 @@ The preceding example is equivalent to the following JSON.
 
 ## Multiple-line declarations
 
-You can now use multiple lines in function, array and object declarations. This feature requires [Bicep CLI version 0.7.X or higher](./install.md).
+You can now use multiple lines in function, array, and object declarations. This feature requires [Bicep CLI version 0.7.X or higher](./install.md).
 
 In the following example, the `resourceGroup()` definition is broken into multiple lines.
 
@@ -438,7 +451,7 @@ See [Arrays](./data-types.md#arrays) and [Objects](./data-types.md#objects) for
 ## Known limitations
 
 * No support for the concept of apiProfile, which is used to map a single apiProfile to a set apiVersion for each resource type.
-* User-defined functions are not supported at the moment. However, an experimental feature is currently accessible. For more information, see [User-defined functions in Bicep](./user-defined-functions.md).
+* User-defined functions aren't supported at the moment. However, an experimental feature is currently accessible. For more information, see [User-defined functions in Bicep](./user-defined-functions.md).
 * Some Bicep features require a corresponding change to the intermediate language (Azure Resource Manager JSON templates). We announce these features as available when all of the required updates have been deployed to global Azure. If you're using a different environment, such as Azure Stack, there may be a delay in the availability of the feature. The Bicep feature is only available when the intermediate language has also been updated in that environment.
 
 ## Next steps

articles/azure-resource-manager/bicep/linter-rule-secure-secrets-in-parameters.md

@@ -8,7 +8,7 @@ ms.date: 03/20/2024
 
 # Linter rule - secure secrets in parameters
 
-This rule finds parameters whose names look like secrets but without the [secure decorator](./parameters.md#decorators), for example: a parameter name contains the following keywords:
+This rule finds parameters whose names look like secrets but without the [secure decorator](./parameters.md#use-decorators), for example: a parameter name contains the following keywords:
 
 - password
 - pwd
@@ -24,7 +24,7 @@ Use the following value in the [Bicep configuration file](bicep-config-linter.md
 
 ## Solution
 
-Use the [secure decorator](./parameters.md#decorators) for the parameters that contain secrets. The secure decorator marks the parameter as secure. The value for a secure parameter isn't saved to the deployment history and isn't logged.
+Use the [secure decorator](./parameters.md#use-decorators) for the parameters that contain secrets. The secure decorator marks the parameter as secure. The value for a secure parameter isn't saved to the deployment history and isn't logged.
 
 The following example fails this test because the parameter name may contain secrets.
 

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

@@ -309,7 +309,7 @@ By default, Azure resources are deployed in parallel. When you use a loop to cre
 
 You might not want to update all instances of a resource type at the same time. For example, when updating a production environment, you may want to stagger the updates so only a certain number are updated at any one time. You can specify that a subset of the instances be batched together and deployed at the same time. The other instances wait for that batch to complete.
 
-To serially deploy instances of a resource, add the [batchSize decorator](./file.md#resource-and-module-decorators). Set its value to the number of instances to deploy concurrently. A dependency is created on earlier instances in the loop, so it doesn't start one batch until the previous batch completes.
+To serially deploy instances of a resource, add the [batchSize decorator](./file.md#decorators). Set its value to the number of instances to deploy concurrently. A dependency is created on earlier instances in the loop, so it doesn't start one batch until the previous batch completes.
 
 ```bicep
 param location string = resourceGroup().location