feat: new Bicep linter rule use-parameter-descriptions

[johnlokerse]

Description

This change adds a new Bicep linter rule called use-parameter-descriptions. Default the rule level is off but when set to error it checks if the parameter has either the @sys.description or @description decorator above a parameter. Additionally, it checks if the description is not empty.

@anthony-c-martin @stephaniezyen This implements issue #9453 and #5595.

Example Usage

It works through the bicep linter command or using the VSCode extension:

Checklist

• I have read and adhere to the contribution guide.

Microsoft Reviewers: Open in CodeFlow

[johnlokerse]

Documentation is needed for this

[johnlokerse]

@anthony-c-martin does anyone on the team have time for a review? 😃

[slavizh]

@johnlokerse does it works for types as well? Would be very good if it applies to types as well or if there is separate rule for it. There is one exception for types though - discriminator. for the example below it should not apply as the description for foo is where foo is referenced. If there is description directly on the type it does not appear anywhere.

...
@discriminator('type)
type foo = foo1 | foo2
...

[johnlokerse]

@johnlokerse does it works for types as well? Would be very good if it applies to types as well or if there is separate rule for it. There is one exception for types though - discriminator. for the example below it should not apply as the description for foo is where foo is referenced. If there is description directly on the type it does not appear anywhere.

...
@discriminator('type)
type foo = foo1 | foo2
...

@slavizh This can be done. I would do it separately from this linter, though, since not everyone wants to put descriptions on properties in types or on the type itself. The same thing applies to variables and outputs if you ask me.

Or as another option we introduce a configuration to the new use-descriptions linter rule, just like use-recent-api-versions has with the maxAllowedAgeInDays configuration in the bicepconfig.json. Like so:

	"analyzers": {
		"core": {
			"rules": {
				"use-recent-api-versions": {
					"level": "warning",
					"maxAllowedAgeInDays": 500
				},
				"use-descriptions": {
					"level": "error",
					"variables": false,
					"userDefinedTypes": true,
					"parameters": true,
					"outputs": true
				}
			}
		}
	}

[anthony-c-martin]

Or as another option we introduce a configuration to the new use-descriptions linter rule, just like use-recent-api-versions has with the maxAllowedAgeInDays configuration in the bicepconfig.json. Like so:

@johnlokerse - the changes in this PR look good to me, but I think it would be a good idea to close on this discussion first - I wouldn't want to release something and then immediately change it.