Skip to content

Render educational notes from the compiler #1395

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
daveyc123 opened this issue Feb 17, 2025 · 1 comment
Closed

Render educational notes from the compiler #1395

daveyc123 opened this issue Feb 17, 2025 · 1 comment
Assignees
@rbenegal
Labels
enhancement New feature or request

Comments

@daveyc123
Copy link
Contributor

The Swift compiler exposes educational notes for certain diagnostics. These notes are markdown files that describe the diagnostic along with examples.

For example, the following code:

protocol P {}

/// A description
struct S {
  let p: some P
}

Results in a diagnostic Property declares an opaque return type, but has no initializer expression from which to infer an underlying type which includes an educational note detailed https://github.com/swiftlang/swift/blob/main/userdocs/diagnostics/opaque-type-inference.md. These markdown files are included in the toolchain under usr/share/doc/swift/diagnostics

Sourcekit-lsp supports sending the path to the markdown file along with the diagnostic, but the VSCode behavior is to open the educational note for editing.

Instead, it should show it as rendered markdown.
@daveyc123 daveyc123 added the enhancement New feature or request label Feb 17, 2025
@award999 award999 moved this from Unscreened to Todo in Swift Extension for Visual Studio Code Feb 26, 2025
daveyc123 added a commit to daveyc123/vscode-swift that referenced this issue Mar 7, 2025
@daveyc123
Improve UX around educational notes
9f23742 
The Swift compiler contains educational notes to further describe
diagnostics [1]. These educational notes are documented in markdown
files that are contained within the toolchain.

Sourcekit LSP includes a link to the local markdown file when returning
diagnostics that have an associated educational note (as part of the
diagnostic code). The default behaviour in VSCode is to present these
as a link in the diagnostic hover, and open the editor to the markdown
file when the link is clicked.

This PR updates the behaviour for educational notes to instead open
the link using the markdown preview, which shows nicely rendered
content. It also updates the link in the hover to show "More
 Information" instead of the code.

Issue: swiftlang#1395

[1] https://github.com/swiftlang/swift/tree/main/userdocs/diagnostics
daveyc123 added a commit to daveyc123/vscode-swift that referenced this issue Mar 7, 2025
@daveyc123
Improve UX around educational notes
bda2c7b 
The Swift compiler contains educational notes to further describe
diagnostics [1]. These educational notes are documented in markdown
files that are contained within the toolchain.

Sourcekit LSP includes a link to the local markdown file when returning
diagnostics that have an associated educational note (as part of the
diagnostic code). The default behaviour in VSCode is to present these
as a link in the diagnostic hover, and open the editor to the markdown
file when the link is clicked.

This PR updates the behaviour for educational notes to instead open
the link using the markdown preview, which shows nicely rendered
content. It also updates the link in the hover to show "More
 Information" instead of the code.

Issue: swiftlang#1395

[1] https://github.com/swiftlang/swift/tree/main/userdocs/diagnostics
daveyc123 added a commit to daveyc123/vscode-swift that referenced this issue Mar 7, 2025
@daveyc123
Improve UX around educational notes
5d840a2 
The Swift compiler contains educational notes to further describe
diagnostics [1]. These educational notes are documented in markdown
files that are contained within the toolchain.

Sourcekit LSP includes a link to the local markdown file when returning
diagnostics that have an associated educational note (as part of the
diagnostic code). The default behaviour in VSCode is to present these
as a link in the diagnostic hover, and open the editor to the markdown
file when the link is clicked.

This PR updates the behaviour for educational notes to instead open
the link using the markdown preview, which shows nicely rendered
content. It also updates the link in the hover to show "More
 Information" instead of the code.

Issue: swiftlang#1395

[1] https://github.com/swiftlang/swift/tree/main/userdocs/diagnostics
daveyc123 added a commit to daveyc123/vscode-swift that referenced this issue Mar 7, 2025
@daveyc123
Improve UX around educational notes
04a3fcf 
The Swift compiler contains educational notes to further describe
diagnostics [1]. These educational notes are documented in markdown
files that are contained within the toolchain.

Sourcekit LSP includes a link to the local markdown file when returning
diagnostics that have an associated educational note (as part of the
diagnostic code). The default behaviour in VSCode is to present these
as a link in the diagnostic hover, and open the editor to the markdown
file when the link is clicked.

This PR updates the behaviour for educational notes to instead open
the link using the markdown preview, which shows nicely rendered
content. It also updates the link in the hover to show "More
 Information" instead of the code.

Issue: swiftlang#1395

[1] https://github.com/swiftlang/swift/tree/main/userdocs/diagnostics
@daveyc123 daveyc123 mentioned this issue Mar 7, 2025
Merged
daveyc123 added a commit to daveyc123/vscode-swift that referenced this issue Mar 7, 2025
@daveyc123
Improve UX around educational notes
33cc9e7 
The Swift compiler contains educational notes to further describe
diagnostics [1]. These educational notes are documented in markdown
files that are contained within the toolchain.

Sourcekit LSP includes a link to the local markdown file when returning
diagnostics that have an associated educational note (as part of the
diagnostic code). The default behaviour in VSCode is to present these
as a link in the diagnostic hover, and open the editor to the markdown
file when the link is clicked.

This PR updates the behaviour for educational notes to instead open
the link using the markdown preview, which shows nicely rendered
content. It also updates the link in the hover to show "More
 Information" instead of the code.

Issue: swiftlang#1395

[1] https://github.com/swiftlang/swift/tree/main/userdocs/diagnostics
daveyc123 added a commit that referenced this issue Mar 7, 2025
@daveyc123
Improve UX around educational notes (#1423)
db7a431 
The Swift compiler contains educational notes to further describe
diagnostics [1]. These educational notes are documented in markdown
files that are contained within the toolchain.

Sourcekit LSP includes a link to the local markdown file when returning
diagnostics that have an associated educational note (as part of the
diagnostic code). The default behaviour in VSCode is to present these
as a link in the diagnostic hover, and open the editor to the markdown
file when the link is clicked.

This PR updates the behaviour for educational notes to instead open
the link using the markdown preview, which shows nicely rendered
content. It also updates the link in the hover to show "More
 Information" instead of the code.

Issue: #1395

[1] https://github.com/swiftlang/swift/tree/main/userdocs/diagnostics
@award999 award999 added the needs verification Issue has been fixed, but requires verification before closing label Mar 21, 2025
@award999 award999 moved this from Todo to Needs Verification in Swift Extension for Visual Studio Code Mar 21, 2025
@rbenegal rbenegal assigned rbenegal and unassigned matthewbastien Mar 27, 2025
@rbenegal
Copy link
Contributor

Confirmed that the educational notes now show up as rendered markdown instead of markdown for editing on a recent pre-release version (version 2.1.20250327 commit 882a038) with the following swift versions on different platforms (as provided by swiftc -v:

Apple Swift version 6.1 (swiftlang-6.1.0.110.21 clang-1700.0.13.3)
Target: arm64-apple-macosx15.0

Swift version 6.1-dev (LLVM fc8af60ca909f22, Swift fc66ec88fb2737b)
Target: x86_64-unknown-windows-msvc

Swift version 6.2-dev (LLVM 162ee50b401fff2, Swift 57288d13c9f3c02)
Target: aarch64-unknown-linux-gnu

Note: Swift 6.1 or higher will be required to see educational notes.

@rbenegal rbenegal removed the needs verification Issue has been fixed, but requires verification before closing label Mar 28, 2025
@rbenegal rbenegal moved this from Needs Verification to Done in Swift Extension for Visual Studio Code Mar 28, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@rbenegal rbenegal

Labels
enhancement New feature or request
Projects
Swift Extension for Visual Studio Code
Archived in project
Milestone
No milestone
Development

No branches or pull requests
4 participants
@daveyc123 @matthewbastien @award999 @rbenegal