@description attribute to document params, outputs, resources & vars and show description hovers

[anthony-c-martin]

We should provide a mechanism to enhance declarations with documentation that can show up in hovers.

This would be especially useful when mousing over module parameters or outputs which are defined in a separate file, or references to variables defined elsewhere in the document. We could also potentially consider using it to generate ARM JSON metadata fields.

Example:

@description('The geo location of the resources to deploy')
param string location

@description('The name of the storage account')
param string stgAccName

@description('Some human-readable text about this resource')
resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: stgAccName
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

@description('The blob storage endpoint URI')
output storageUri string = stg.properties.primaryEndpoints.blob

Originally discussed here: #64 (comment)

EDIT 2021-08-09 - changed @doc() to @description() in this proposal, as it has already been implemented for param.

[majastrz]

For parameters we already do support @description('...'), but it's not possible to apply it to all types of declarations we have. We definitely should show this information in hovers.

[rahalan]

I also miss the @description property for outputs, as ARM is supporting that.

[alex-frankel]

cc @bmoore-msft

Where are these descriptions consumed and displayed? I didn't realize ARM Template outputs supported a description property

[rahalan]

Hi Alex, We use it for documentation purpose, same as for inputs. It should help a consumer of an ARM template to understand what it is outputting. We have an extensive library of ARM templates in https://aka.ms/iacs where we used it so far. It should help users of those files to utilize them quickly. Cheers, Rainer From: Alex Frankel ***@***.***> Sent: Sonntag, 14. März 2021 21:23 To: Azure/bicep ***@***.***> Cc: Rainer Halanek ***@***.***>; Comment ***@***.***> Subject: Re: [Azure/bicep] @doc attribute to add documentation for params, outputs, resources & vars (#1665) cc @bmoore-msft<https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fbmoore-msft&data=04%7C01%7CRainer.Halanek%40microsoft.com%7C4476beb31b76434acbc008d8e72701ef%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637513502040838529%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=nJC1sWL%2Fbby5S2OkD4Bd9dAGmVIQpya0KpiyEcgfLiA%3D&reserved=0> Where are these descriptions consumed and displayed? I didn't realize ARM Template outputs supported a description property — You are receiving this because you commented. Reply to this email directly, view it on GitHub<https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FAzure%2Fbicep%2Fissues%2F1665%23issuecomment-798973311&data=04%7C01%7CRainer.Halanek%40microsoft.com%7C4476beb31b76434acbc008d8e72701ef%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637513502040848487%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=D2DhSuGWIRtzjdAdJBRlIJMTsnX%2FXVX8Tcd33Wb%2FVPI%3D&reserved=0>, or unsubscribe<https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAOYDALAFSEZRSHPMAREDCQ3TDULLPANCNFSM4YNIXFLQ&data=04%7C01%7CRainer.Halanek%40microsoft.com%7C4476beb31b76434acbc008d8e72701ef%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637513502040848487%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=YgY%2B3a4D8iJrvqYFiFu7V9L2gv11BHsmv0AP%2BqxqLyw%3D&reserved=0>.

[alex-frankel]

Got it - I see you are parsing out the descriptions in the README, so the use case definitely makes sense.

[bmoore-msft]

the metadata property is a generic language construct - we (ARM) only use it on params afaiki but some RPs (and I'm sure customers @rahalan) use it in other places in the template (outputs, resources).

[BernieWhite]

@alex-frankel @metadata already works great for properties and decompiles nicely too. Top level metadata would be great.

https://azure.github.io/PSDocs.Azure/using-metadata/

Azure/PSDocs.Azure#106

[anthony-c-martin]

Note - renaming from @description() to @doc() would be a fairly annoying breaking change, so I'm proposing we keep it as @description() at this point.

The main thing I'm after here is to allow annotating any declaration (var/output/resource), and to have this information show up in symbol hovers both in the file, and across modules for param/output.

[bmoore-msft]

so thinking of adding @doc to vars (for example)? or adding @description to vars?

I would lean toward the latter since optimizing for client consumption of it rather than the tools...

[anthony-c-martin]

so thinking of adding @doc to vars (for example)? or adding @description to vars?

I would lean toward the latter since optimizing for client consumption of it rather than the tools...

The latter. I'll update the title & description of this issue to clarify that.