improve decorators

Author: tfitzmac

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

@@ -2,7 +2,7 @@
 title: Bicep file structure and syntax
 description: Describes the structure and properties of a Bicep file using declarative syntax.
 ms.topic: conceptual
-ms.date: 09/30/2021
+ms.date: 10/01/2021
 ---
 
 # Understand the structure and syntax of Bicep files
@@ -179,6 +179,8 @@ param name string
 param description string
 ```
 
+For more information, see [Decorators](parameters.md#decorators).
+
 ## Variables
 
 Use variables for complex expressions that are repeated in a Bicep file. For example, you might add a variable for a resource name that is constructed by concatenating several values together.

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

@@ -4,7 +4,7 @@ description: Describes how to define parameters in a Bicep file.
 author: mumian
 ms.author: jgao
 ms.topic: conceptual
-ms.date: 09/30/2021
+ms.date: 10/01/2021
 ---
 
 # Parameters in Bicep
@@ -51,7 +51,17 @@ You can use another parameter value to build a default value. The following temp
 
 ## 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 sections show how to use these 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'
+```
 
 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.
 
@@ -62,7 +72,9 @@ param name string
 param description string
 ```
 
-## Secure parameters
+The available decorators are described in the following sections.
+
+### Secure parameters
 
 You can mark string or object parameters as secure. The value of a secure parameter isn't saved to the deployment history and isn't logged.
 
@@ -74,7 +86,7 @@ param demoPassword string
 param demoSecretObject object
 ```
 
-## Allowed values
+### 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.
 
@@ -86,7 +98,7 @@ You can define allowed values for a parameter. You provide the allowed values in
 param demoEnum string
 ```
 
-## Length constraints
+### Length constraints
 
 You can specify minimum and maximum lengths for string and array parameters. You can set one or both constraints. For strings, the length indicates the number of characters. For arrays, the length indicates the number of items in the array.
 
@@ -102,7 +114,7 @@ param storageAccountName string
 param appNames array
 ```
 
-## Integer constraints
+### Integer constraints
 
 You can set minimum and maximum values for integer parameters. You can set one or both constraints.
 
@@ -112,7 +124,7 @@ You can set minimum and maximum values for integer parameters. You can set one o
 param month int
 ```
 
-## Description
+### Description
 
 To help users understand the value to provide, add a description to the parameter. When deploying the template through the portal, the description's text is automatically used as a tip for that parameter. Only add a description when the text provides more information than can be inferred from the parameter name.