[AVM Question/Feedback]: Add examples to the readme

[ReneHezser]

Check for previous/existing GitHub issues

• I have checked for previous/existing GitHub issues

Description

I'd like to have examples for parameters and UDTs to the generated readme. The contribution guide already mentions this feature here, but the examples are not added to the readme.

Here are some examples on how I add examples:

@metadata({
  example: '''
  - ['[email protected]']
  - ['[email protected]','[email protected]']
  '''
})
@description('Optional. The email recipient value to receive alerts.')
param additionalRecipients array = []

@metadata({
  example: '''
  {
      "key1": "value1",
      "key2": "value2"
  }
  '''
})
@description('Optional. Tags of the resource.')
param tags object?

type replicaSetType = {
  @description('Required. Virtual network location.')
  location: string

  @metadata({
    example: '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/<resourceGroup>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>'
  })
  @description('Required. The id of the subnet that Domain Services will be deployed on. The subnet has some requirements, which are outlined in the [notes section](#Network-Security-Group-NSG-requirements-for-AADDS) of the documentation.')
  subnetId: string
}[]?

@description('Optional. Collection of private container registry credentials for containers used by the Container app.')
@metadata({
  example: '''[
  {
    "server": "myregistry.azurecr.io",
    "identity": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myManagedIdentity"
  },
  {
    "server": "myregistry2.azurecr.io",
    "identity": "system"
  }
  ,
  {
    "server": "myregistry3.azurecr.io",
    "username": "myusername",
    "passwordSecretRef": "secret-name"
  }
]'''
})
param registries registryType?

type registryType = {
  @description('Required. The FQDN name of the container registry.')
  @metadata({ example: 'myregistry.azurecr.io' })
  server: string

  @description('Optional. The resource ID of the (user) managed identity, which is used to access the Azure Container Registry.')
  @metadata({
    example: '''
    user-assigned identity: /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myManagedIdentity
    system-assigned identity: system
    '''
  })
  identity: string?

  @description('Optional. The username for the container registry.')
  username: string?

  @description('Conditional. The name of the secret contains the login password. Required if `username` is not null.')
  passwordSecretRef: string?
}[]?

[AlexanderSehr]

The challenge I see with this approach (as opposed to leverage the UDTs documentation itself and or the usage examples) is that this introduces untested code, that 'can' run stale. We used to actually have a lot of examples called 'Parameter Usage xzy' in CARML, but soon found out that 90% were outdated within a year without anybody noticing but users that encountered issues.

I'm not saying the idea is bad - it just comes at quite a cost that I'm not sure how to avoid.

[ReneHezser]

I understand the challenges. This is a must have feature which distinguishes AVM from the usual MS docs and offers real benefits in adoption and usage.
Looking up what the parameter is expecting can be a frustrating and time-consuming task. I want to offer guidance to users.

[ChrisSidebotham]

@ReneHezser - I feel this is addressed with the max tests as we test the largest parameter set possible. Although we do not limit contributors and owners from adding this information to the main.bicep files, it would be at the contributors/owners discretion to enforce this for complex objects that cannot be tested within the max test. We do import the tests into the readme to give the users real world examples of the parameter structure.

Any additional items to this should be opened as a issue on the target module

[AlexanderSehr]

@ChrisSidebotham, I think @ReneHezser is aware that the tests are imported. I've seen for several parameters, that metadata was added which is just not imported into the module readme at this point.
I guess it would make sense to bring this up in the team if we want to just support adding examples and relying on the module owners to maintain them at all times, are restrict examples to everything which is validated across a module's tests cases instead. What do you think?

[ChrisSidebotham]

@AlexanderSehr - Today we had a discussion about BCPNFR1 which I feel also addresses this. CARML Migrated moduleshad been exempt from the MUST use UDT's for complex objects and arrays until the Migration was complete. Now the expectation is that we will drive tis into the "migrated" modules. In which the usage becomes alot simpler with autocomplete functionality - lets mark this for discussion in the next team call

[AlexanderSehr]

@AlexanderSehr - Today we had a discussion about BCPNFR1 which I feel also addresses this. CARML Migrated moduleshad been exempt from the MUST use UDT's for complex objects and arrays until the Migration was complete. Now the expectation is that we will apply this to the "migrated" modules. In which the usage becomes alot simpler with autocomplete functionality - lets mark this for discussion in the next team call

UDTs would certainly help and cover most of the effort. But they're not 1:1 the same as an example. E.g. the UDT would say 'this property is a resource Id' in the property's name or description and if you know how a resourceId needs to look like great. If somebody does not, an example would maybe help.
I'd think that this is where this could/should land - on the UDT properties. This would make it also a whole lot easier to maintain as @ReneHezser in this case would not need to describe the entire object in an example (which could run stale if the structure changes), but the individua properties of the object (which are very likely only to change in the way that they're removed / replaced).
If I'm not making any sense, I can add an example later 😄

[ReneHezser]

I added another example to the initial post showing different usage scenarios of parameter combinations. Some of this can be done with the Condition in the description, but I still see enormous value in the whole example.