Show version-specific docs links on resource hovers#20016
Merged
andyleejordan merged 3 commits intoJul 7, 2026
Conversation
The hover that shows a resource's signature and a `[View Documentation]` link previously only appeared over the resource *name*. This makes the Azure docs link hard to discover, since the type string (e.g. `'Microsoft.Storage/storageAccounts@2023-01-01'`) is the more natural thing to hover when you want to know about a resource type. `BicepSymbolResolver.ResolveSymbol` returns null over the type string because only the whole declaration and the name identifier bind to the `ResourceSymbol` — the type `StringSyntax` is not in the symbol bindings. So `BicepHoverHandler` now falls back, when symbol resolution fails, to matching the type string directly and constructing a `SymbolResolutionResult` that points the resource symbol at the type string. That lets the hover reuse the exact same markdown and range logic as the name hover — the type string just becomes the origin node, so the docs link renders identically and the range highlights the type. I scoped this to the hover handler rather than broadening the shared symbol resolver, since `ResolveSymbol` also backs go-to-definition, find-references, rename, and document-highlight — we don't want those to start acting on the resource from the type string. Fixes #16178 Drafted by Copilot (Claude Opus 4.8). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The hover's "View Documentation" link always pointed at Learn's versionless page for a type, even when the resource pinned a concrete API version. That page describes the latest schema, which can differ from the version being authored, so the link didn't necessarily match the resource. Learn publishes a page per API version alongside the versionless page, so we now insert the pinned version between the provider and the type path — e.g. `Microsoft.Storage/storageAccounts@2026-04-01` links to `.../microsoft.storage/2026-04-01/storageaccounts?pivots=deployment-language-bicep`. When a resource somehow has no version we keep the existing versionless URL. Updated the existing hover URL assertions accordingly (the test RP uses `@2020-01-01`). Drafted by Copilot (Claude Opus 4.8). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
|
Test this change out locally with the following install scripts (Action run 28881152796) VSCode
Azure CLI
|
Contributor
Author
The vscode-bicep e2e hover tests weren't updated alongside the LangServer changes on this branch. This does both: - Adds a case that hovers the resource *type* string (not just the symbolic name) and asserts the same signature + docs link, exercising the issue #16178 feature end-to-end through VS Code. - Updates the existing symbolic-name assertion to the version-specific Learn URL (`.../microsoft.network/2020-06-01/virtualnetworks?...`) to match the new behavior. Verified locally against the min-supported VS Code (all hover tests pass). The stable-VS-Code pass fails to launch here on an unrelated macOS Unix-socket path-length limit caused by the long worktree path, not by these tests. Drafted by Copilot (Claude Opus 4.8). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
andyleejordan
changed the title
andyleejordan
deleted the
andyleejordan-extend-hover-doc-link-to-resource-type
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #16178.
We already render a View Documentation link when hovering a resource's
name, but as @anthony-c-martin noted it's hard to discover there. This PR
makes it discoverable and version-accurate:
the same hover (signature + docs link) now also shows when hovering over
Microsoft.Storage/storageAccounts@2023-01-01, not just the symbol name.requested, the link now points at the pinned API version's Learn page,
e.g.
.../microsoft.storage/2023-01-01/storageaccounts?pivots=deployment-language-bicepinstead of the versionless "latest" page. It falls back to the versionless
URL when a resource has no version.
Why this is safe
The type-string hover is implemented as a hover-only fallback in
BicepHoverHandler; it does not touch the sharedBicepSymbolResolver. Thatresolver backs rename, references, definition, etc., so mapping the type string
to the resource symbol there would (for example) make "rename symbol" over the
type string silently rename the resource. Keeping it local to the hover handler
avoids that blast radius.
Out of scope
The original issue also asked for clicking a resource type/ID/version to
open docs. After looking into it, opening an external URL on click of a symbol
isn't really a VS Code idiom — the discoverable, clickable link inside the hover
is the idiomatic surface for this, so we're intentionally not adding
click-to-open behavior here.
Drafted by Copilot (Claude Opus 4.8).
Microsoft Reviewers: Open in CodeFlow