Skip to content
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

Render educational notes from the compiler #1395

Open
daveyc123 opened this issue Feb 17, 2025 · 0 comments
Open

Render educational notes from the compiler #1395

daveyc123 opened this issue Feb 17, 2025 · 0 comments
Assignees
@daveyc123
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@daveyc123 daveyc123

Labels
enhancement New feature or request
Projects
Swift Extension for Visual Studio Code
Status: Todo
Milestone
No milestone
Development

No branches or pull requests
1 participant
@daveyc123