Azure / Azure/bicep

Extending the ResourceType class to allow custom documentation links for bicep extension types

Open
#17,429 0 comments 2 reactions 1 assignee Claimed by @shenglol View on GitHub
enhancement story: extensibility
Dominant language
Bicep
Stars
3.6k
Forks
830
Avg merge
1d 21m
Merged PRs (30d)
79

Description

**Is your feature request related to a problem? Please describe.**
Nowadays, when you hover the name of resource defined in Bicep, a link to the documentation of the resource is displayed in the context windows that appears.

![Image](https://github.com/user-attachments/assets/372ae592-66ff-4971-9681-4da3a945eb16)

Because this link is generated exclusively for Azure resources and the way it is generated is specially tailored for those resources as depicted by the code below, it is impossible for extensions such as the kubernetes, msgraph or any third party extension to provide documentation for their types.

```csharp
private static string? TryGetTypeDocumentationLink(ResourceSymbol resource)
{
if (resource.TryGetResourceType() is { } resourceType &&
resourceType.DeclaringNamespace.ExtensionNameEquals(AzNamespaceType.BuiltInName) &&
resourceType.DeclaringNamespace.ResourceTypeProvider.HasDefinedType(resourceType.TypeReference))
{
var provider = resourceType.TypeReference.TypeSegments.First().ToLowerInvariant();
var typePath = resourceType.TypeReference.TypeSegments.Skip(1).Select(x => x.ToLowerInvariant());

return $"https://learn.microsoft.com/azure/templates/{provider}/{string.Join('/', typePath)}?pivots=deployment-language-bicep";
}

return null;
}
```

**Describe the solution you'd like**
The resource type schema would accept a new property `documentationLink` or `description` that would allow extension authors to provide documentation links for their resource types. The language server would then check and read this new property to display documentation links if the resource is not an Azure type.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.