Feature Request: Comment based parameter description

[JustinGrote]

Is your feature request related to a problem? Please describe.
parameters should always have descriptions to make it easy for someone to construct a parameter.json file and understand what is happening, however there is still far too much boilerplate to add a description to a parameter when they should be present for nearly all parameter definitions, not to mention losing the terse default syntax.

param MyString string {
  metadata: {
    description: 'String required for this module.'
  }
  default: 'test'
}

Describe the solution you'd like
Take a page from C# and Powershell Comment Based Help and allow comments directly above the parameters to be picked up as description. Maybe require a keyword DESCRIPTION: to distinguish from random comments to avoid user confusion.

The below would produce the same result as above:

// String required for this module
param MyString string = 'test'

It could also be sameline, which is already used in examples like https://github.com/Azure/bicep/blob/main/docs/tutorial/01-simple-template.md, though it is preferred as a separate like so that pull requests/etc. can update documentation without affecting a parameter line.

param MyString string = 'test' // String required for this module

[anthony-c-martin]

Note that you can (as of Bicep 0.3) use decorators to accomplish this:

@description('String required for this module')
param MyString string = 'test'

With #1665 we should show this information in hovers in VSCode.

[JustinGrote]

@anthony-c-martin totally whiffed the decorators announcement. Thanks, I'll take this approach for now, but will leave the issue open as an alternative to decorators if the team wants to consider.

[alex-frankel]

We are going to go with the @doc decorator, so we are not going to plan to do this as well. Closing for now. Let us know if there are any concerns.