# Surfacing educational notes for compiler errors **URL:** \ **Category:** Source Tooling\ **Tags:** diagnostics, educational-notes\ **Created:** [February 21, 2025, 10:50pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023 "2025-02-21T22:50:28Z")\ **Posts on this page:** 17\ **Page:** 1
**Author:** ![hborla](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/hborla/32/27563_2.png) [@hborla](https://forums.swift.org/u/hborla)\ **Post date:** [February 21, 2025, 10:50pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/1 "2025-02-21T22:50:28Z")
@Joseph_Heck had some good questions about surfacing educational notes in another thread. I thought I'd answer them in a new discussion thread because it's a slightly different topic from the original one. > [@Feedback wanted: confusing concurrency diagnostic messages](https://forums.swift.org/t/feedback-wanted-confusing-concurrency-diagnostic-messages/72523/47): > > My main question is how are they surfaced - what's rendering the markdown (if anything) when it's presented, and what's the context for the user when they're finding/reading these? Is it primarily GitHub's web interface, or multiple different avenues? The educational notes are currently included as markdown files in the Swift toolchain, but no tools are consuming and rendering them. The goal is to render them via multiple different avenues. For example: - On the Swift website: [Provide an index of educational notes for compiler errors · Issue #910 · swiftlang/swift-org-website · GitHub](https://github.com/swiftlang/swift-org-website/issues/910) - In the VSCode Swift extension: [Render educational notes from the compiler · Issue #1395 · swiftlang/vscode-swift · GitHub](https://github.com/swiftlang/vscode-swift/issues/1395) - At the command line via a `swift explain` action that takes an educational note identifier or similar. Each of these has a slightly different workflow experience. An educational notes index would primarily be for browsing and searching. In the VSCode Swift extension or at the command line, you'd navigate to an educational note directly from an error message that you got while building code. > [@Feedback wanted: confusing concurrency diagnostic messages](https://forums.swift.org/t/feedback-wanted-confusing-concurrency-diagnostic-messages/72523/47): > > One thing I noted, but I don't know if it makes a difference, is that the code voice blocks (triple-backtick bits) were all `swift`, but the blocks were inconsistently labeled. Will that cause any issues for how/when they're rendered (DocC, for example, assumed `swift` as a default language for syntax highlighting - but other setups may not) Some of the code blocks are not labeled `swift` because they are command-line output with error messages. I followed the same style that's already used in the Swift migration guide, where the original source example uses `swift` code blocks and the diagnostics use plain triple backticks to render as plain text. This seems to work okay for rendering via DocC (for example: [Documentation](https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/commonproblems)), but there might also be a better way to display compiler errors in documentation like this. ---
**Author:** ![compnerd](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/compnerd/32/2165_2.png) [@compnerd](https://forums.swift.org/u/compnerd)\ **Post date:** [February 21, 2025, 11:24pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/2 "2025-02-21T23:24:32Z")
Interesting! Is this something that has been there for a while? I don't think that we have included any such files in the Windows toolchain distribution in the past, and I want to ensure that if this is meant to be distributed, we try to include them in the 6.1 release cycle if they are present. ---
**Author:** ![hborla](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/hborla/32/27563_2.png) [@hborla](https://forums.swift.org/u/hborla)\ **Post date:** [February 21, 2025, 11:39pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/3 "2025-02-21T23:39:04Z")
> [@compnerd](#): > > Interesting! Is this something that has been there for a while? The educational note mechanism has been around [for a while](https://github.com/swiftlang/swift/pull/30583). Note that the `-print-educational-notes` flag mentioned in the PR description stopped working when the new Swift diagnostic formatter was enabled by default for command-line diagnostics. However, this flag dumped the full educational note content for every diagnostic emitted, and I don't think that's the ideal command-line experience. > [@compnerd](#): > > I don't think that we have included any such files in the Windows toolchain distribution in the past, and I want to ensure that if this is meant to be distributed, we try to include them in the 6.1 release cycle if they are present. Up until now, I think we've had a "chicken and egg" problem - no tools were consuming the educational notes because there were so few of them, and more educational notes haven't been added because they're not surfaced anywhere. I've been working on fixing the coverage problem, because I've been writing explanations for concurrency errors anyway when answering questions. There are still very few of them on `release/6.1`, but I plan to add a lot more on `main`! ---
**Author:** ![compnerd](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/compnerd/32/2165_2.png) [@compnerd](https://forums.swift.org/u/compnerd)\ **Post date:** [February 22, 2025, 1:13am UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/4 "2025-02-22T01:13:48Z")
> [@hborla](#): > > There are still very few of them on `release/6.1`, but I plan to add a lot more on `main`! Okay, sounds like it might not be worth it for release/6.1 then? We should get them added on main to prepare for the next rebranch though. Is there an install component that will install these or is that infrastructure that needs to be stood up? The Windows packaging tries to avoid pulling anything from the source tree and has been trying to build up a staged toolchain install to use to package up the toolchain distribution. ---
**Author:** ![xedin](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/xedin/32/309_2.png) [@xedin](https://forums.swift.org/u/xedin)\ **Post date:** [February 25, 2025, 7:52pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/5 "2025-02-25T19:52:09Z")
The install rule is in [userdocs/CMakeLists.txt](https://github.com/swiftlang/swift/blob/main/userdocs/CMakeLists.txt) at the moment, build-script doesn't have anything special for them: ```swift swift_install_in_component(DIRECTORY diagnostics DESTINATION "share/doc/swift" COMPONENT compiler) ``` ---
**Author:** ![compnerd](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/compnerd/32/2165_2.png) [@compnerd](https://forums.swift.org/u/compnerd)\ **Post date:** [February 25, 2025, 7:57pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/6 "2025-02-25T19:57:23Z")
Thanks @xedin, I had figured that out. That actually is the special thing that we need for windows. There is the COMPONENT that we list so that we build the minimal amount of code. This is now packaged up and should be in the newer installers as they come out. ---
**Author:** ![Douglas\_Gregor](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/douglas_gregor/32/1362_2.png) [@Douglas\_Gregor](https://forums.swift.org/u/Douglas_Gregor)\ **Post date:** [February 28, 2025, 4:36pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/7 "2025-02-28T16:36:17Z")
Hey all, [SE-0443](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0443-warning-control-flags.md) introduced diagnostic groups, which have many similarities with educational notes: they tag specific diagnostics produced by the compiler and associate documentation with them. I've been [aligning the implementation scheme](https://github.com/swiftlang/swift/pull/79694) for these features so that the documentation for a diagnostic group is available in the same way as an educational note. I've also been thinking about the user experience on the command line: how can we help users find the documentation we write for diagnostics? The compiler currently has `-print-diagnostic-groups`, which prints the name of a diagnostic group in square brackets at the end of the message, e.g., ```swift t.swift:2:7: warning: expression uses unsafe constructs but is not marked with 'unsafe' [StrictMemorySafety] ``` That's useful, but you need to know that `[StrictMemorySafety]` means it's a diagnostic group, and then go hunting in the toolchain for the corresponding `strict-memory-safety.md`. The compiler also has a hidden `-print-educational-notes`, which renders the Markdown for educational notes into the terminal: ```swift t.swift:2:1: error: non-nominal type 'Crap' (aka '() -> ()') cannot be extended extension Crap {} ^ ~~~~ Nominal Types In Swift, a type is considered a nominal type if it has been explicitly named by a declaration somewhere in code. Examples of nominal types include classes, structures and enumerations. Nominal types are an important concept in Swift because they may conform to protocols, be extended, and have values created using the initializer syntax 'MyType()'. In contrast, non-nominal types do not have these capabilities. Many are obtained by composing other types. Examples include function types like '(Int) -> (String)', tuple types like '(Int, String)', metatypes like 'Int.Type', and special types like 'Any' and 'AnyObject'. Since a protocol is named by a declaration in code, it may conform to (in other words, refine) other protocols and it may be extended. However, when written as the type of a constant or variable such as 'let value: MyProtocol', the name refers to a distinct, non-nominal existential type that provides a “box” for a value of any concrete type that conforms to the protocol. The existential type itself does not conform to any protocols and cannot be extended, and a value cannot be created using the initializer syntax 'MyProtocol()'. For more on using existential types, see [Protocols as Types](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html#ID275) in The Swift Programming Language. ``` This provides the documentation, but: it's quite verbose, the terminal isn't necessarily the best place to read this documentation, and you likely don't want to see this most of the time. In both cases, you have to find the flag to turn it on. I think we can do a lot better for our users here! I suggest that, by default, we print the diagnostic group name or educational note name in brackets with a leading `#` to imply that it's a reference. Then, at the end of the compile, provide links to the documentation for each of the diagnostic groups or educational notes that were referenced in any diagnostic above. The result could look like this: ```swift t.swift:2:7: warning: expression uses unsafe constructs but is not marked with 'unsafe' [#StrictMemorySafety] 1 | func somethingUnsafe(x: Int) { 2 | _ = UnsafeRawPointer(bitPattern: x) | |- warning: expression uses unsafe constructs but is not marked with 'unsafe' [^StrictMemorySafety] | |- note: reference to unsafe type 'UnsafeRawPointer' | |- note: reference to initializer 'init(bitPattern:)' involves unsafe type 'UnsafeRawPointer' | `- note: @unsafe conformance of 'UnsafeRawPointer' to protocol '_Pointer' involves unsafe code 3 | } 4 | [#StrictMemorySafety]: /path/to/swift/toolchain/share/doc/swift/diagnostics/strict-memory-safety.md ``` For [terminals that support it](https://github.com/Alhadis/OSC8-Adoption/), we could make the `[#StrictMemorySafety]` a hyperlink to the markdown file and elide the footnotes at the end. We could also consider rendering the markdown into HTML in the toolchain (as part of the install process), so we're not dependent on the user having a nice way to view markdown files by default. What do y'all think? Does this hit the right balance between discoverability and verbosity? What could we do better? Doug ---
**Author:** ![allevato](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/allevato/32/385_2.png) [@allevato](https://forums.swift.org/u/allevato)\ **Post date:** [February 28, 2025, 4:52pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/8 "2025-02-28T16:52:49Z")
That looks really neat! The first thought that comes to mind is that it would be great to make sure this works well in CI/distributed environments, too. When a build is happening remotely, a path into the toolchain may not be relevant to the end user: - I could start a build (say with Bazel) on my physical workstation, but the compile actions are happening on a remote build farm somewhere, and the path that gets relayed back to me on the terminal would be to the remote machine's toolchain, which might be a different path than where I have it installed. - Likewise, if I'm viewing a build log after the fact in a CI environment, chances are I'm reading it in a browser, not on the terminal. Having the note still be navigable there would be a win. Not immediately sure what the answer here is without introducing too much complexity. A flag that lets us replace the toolchain's install dir prefix with an arbitrary string could be interesting, because we could replace it with a URL prefix and then host `/share/doc` in a location reachable for our users. It might be even nicer if [swift.org](http://swift.org) could include docs/educational notes like this as part of automated hosting, like how the LLVM/Clang docs work, so that they're available in a persistent location accessible to everyone on the web, for each version of the toolchain that's released. On a semi-related note, I always find myself wanting to point someone to the description of a `swiftc` flag, and while the equivalent [Clang command line argument reference](https://clang.llvm.org/docs/ClangCommandLineReference.html) page isn't the most user-friendly resource, it does have one major advantage: it _exists_. ---
**Author:** ![Douglas\_Gregor](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/douglas_gregor/32/1362_2.png) [@Douglas\_Gregor](https://forums.swift.org/u/Douglas_Gregor)\ **Post date:** [February 28, 2025, 7:32pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/9 "2025-02-28T19:32:36Z")
> [@allevato](#): > > The first thought that comes to mind is that it would be great to make sure this works well in CI/distributed environments, too. Yes, I could use some help accounting for the cases here. > [@allevato](#): > > A flag that lets us replace the toolchain's install dir prefix with an arbitrary string could be interesting, because we could replace it with a URL prefix and then host `/share/doc` in a location reachable for our users. We already have `-diagnostic-documentation-path `, which is what we prefix to the Markdown file name when showing the path. I think this can also be a URL. Is that sufficient for your uses? > [@allevato](#): > > It might be even nicer if [swift.org](http://swift.org) could include docs/educational notes like this as part of automated hosting, like how the LLVM/Clang docs work, so that they're available in a persistent location accessible to everyone on the web, for each version of the toolchain that's released. I agree that we should have this, but I'm not sure we always want to point at this URL vs. something that's on the user's local machine. I could certainly see wanting to set `-diagnostic-documentation-path https://swift.org/diagnostics/` or similar for CI builds. Doug ---
**Author:** ![allevato](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/allevato/32/385_2.png) [@allevato](https://forums.swift.org/u/allevato)\ **Post date:** [February 28, 2025, 8:06pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/10 "2025-02-28T20:06:54Z")
> [@Douglas\_Gregor](#): > > We already have `-diagnostic-documentation-path `, which is what we prefix to the Markdown file name when showing the path. I think this can also be a URL. Is that sufficient for your uses? I must have missed that one! This is why we need that up-to-date hosted page of flags 😁 I think that would work very well for our use cases. And totally agree that it's reasonable to not make it the default. But if we had the docs uploaded to some reliable versioned hosting, I could definitely see it becoming common in CI workflows to provide a different value there, for convenience. ---
**Author:** ![krilnon](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/krilnon/32/276_2.png) [@krilnon](https://forums.swift.org/u/krilnon)\ **Post date:** [February 28, 2025, 10:57pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/11 "2025-02-28T22:57:05Z")
> [@Douglas\_Gregor](#): > > We could also consider rendering the markdown into HTML in the toolchain (as part of the install process), so we're not dependent on the user having a nice way to view markdown files by default. Another idea in that space… you could use the DocC that (IIRC) ships in the toolchain to render and serve the markdown. ---
**Author:** ![Joseph\_Heck](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/joseph_heck/32/22369_2.png) [@Joseph\_Heck](https://forums.swift.org/u/Joseph_Heck)\ **Post date:** [February 28, 2025, 11:40pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/12 "2025-02-28T23:40:41Z")
I really like how this lays out the information, and most importantly I love the idea of providing a useful, easy to follow reference to where to find more information, a deeper explanation, etc. I think that kind of detail built into the compiler itself (and supported by the language's infrastructure) provides a better developer experience. I don't know if there's a formal limit to a compiler error message, but I'd guess at "a simple sentence", as you're trying to keep something inline with error output, presumably exposed underneath or overlaid into the code itself for easiest marking. More information is frequently useful, especially for new features or for new-to-swift developers. _How_ to wrangle that link is an interesting question - simply because there's tradeoffs with choices, and potentially challenges. In my "ideal world" (meaning I don't really have a clue for how much work I'm suggesting), I'd love to see [swift.org](http://swift.org) directly host such content for the compilers, with stable URLs that were practically an "API contract" for location, so that the Swift compiler - on any platform - could reference it usefully. Maybe that's a lot better built into the toolchain that comes with Swift, and perhaps it should be there as a formal "source of truth". Doing that certainly helps nail down issues relating to versioning and forward and backward compatibility. I'd love to see even the "more detail" sections here reference the formal documentation for Swift - The Swift Programming Language "book", the standard library documentation, and even the libraries in swiftlang that extend the standard library (collections, algorithms, async-algorithms, etc). I think the more we can weave it (loosely!) together, at least pointing to where more information resides, the better it'll be to see a holistic view of how the details connect. It's a little beyond the scope of what you're asking here - but I'd love to see that content, even embedded within the toolchain, in static files at a known (that is, guaranteed for external developer tools to use) location. Maybe sourced in Markdown, or maybe rendered in _simple_ html that developer tools cloud opt into including and displaying alongside the code. The tricky point is the logical extension - as Markdown can start to break down with more advanced formatting features (tables, term lists, and what - if anything - is supported for embedded blocks). But if we're talking about "a couple of sentences, and maybe an HTML hyperlink" we're well beneath the threshold of complexity where different markdown rendering tech starts to make a notable difference. Doing all this for compiler messages as well as educational notes is a great capability win. Today a developer has to search for it, and frequently that's a search engine query. It'd be great to be able to help direct that search a bit to make things easier for the developer to understand what's happening. ---
**Author:** ![Joseph\_Heck](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/joseph_heck/32/22369_2.png) [@Joseph\_Heck](https://forums.swift.org/u/Joseph_Heck)\ **Post date:** [February 28, 2025, 11:46pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/13 "2025-02-28T23:46:20Z")
I see a two challenges with using DocC - although the docc renderer has lovely output that I'd love to see us take advantage of and build on the doc experience already in Swift. The first challenge is the URL construction (the location of the file) is relatively hard to control - it's _always_ under `/documentation/` to support the single-page JS application that's presenting the information with the final URL location pinned to the filename for article-like content. The second is that today it (docc rendering) requires the JavaScript app to be running to see the content, since it's rendering on the fly from the archive. That makes consuming this from arbitrary developer tooling (Xcode to visual studio code to NeoVIM or emacs) far more challenging. That said, if this is an argument in favor of getting static-html-output support into DocC tooling to make it easy to create single or sets of static HTML pages with content, count me in on that! ---
**Author:** ![owenv](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/owenv/32/6137_2.png) [@owenv](https://forums.swift.org/u/owenv)\ **Post date:** [March 1, 2025, 7:27pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/14 "2025-03-01T19:27:24Z")
A few miscellaneous thoughts in no particular order: The local vs CI/remote builds discrepancy is largely why I was originally thinking of exposing a swift-explain executable back in the day - assuming identifiers are stable and the user has a toolchain at least as new as the one which produced a log, it would allow users to just copy and paste a command to access the docs. This is basically a copy of Rust's approach, which has worked out well IMO. If we did that, I think the printed output could look something like: ```swift [#StrictMemorySafety]: swift explain #StrictMemorySafety ``` and perhaps also add the path if attached to a tty ```swift [#StrictMemorySafety]: swift explain #StrictMemorySafety (/path/to/swift/toolchain/share/doc/swift/diagnostics/strict-memory-safety.md) ``` * * * VSCode support: this was added in [Expose diagnostic educational notes as diagnostic codes by owenv · Pull Request #345 · swiftlang/sourcekit-lsp · GitHub](https://github.com/swiftlang/sourcekit-lsp/pull/345) using the DiagnosticCode api in VSCode. These show up as hyperlinks at the end of the diagnostic text which can be opened in the editor. * * * It might be worth moving the notes to a docc catalog even if it's a little different from the traditional use cases. They're loose markdown files right now just because the feature predates docc. Doing so would allow: - Potentially simplifying the Windows installer rules - Adding an optional mode to the hypothetical swift-explain to spin up a local web server instead of printing docs to the terminal I don't think it makes sense to ship HTML artifacts in the toolchain itself - IMO it's useful to keep the content as human-readable as possible in its raw source form ---
**Author:** ![compnerd](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/compnerd/32/2165_2.png) [@compnerd](https://forums.swift.org/u/compnerd)\ **Post date:** [March 2, 2025, 2:21am UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/15 "2025-03-02T02:21:27Z")
> [#StrictMemorySafety]: swift explain #StrictMemorySafety Note that `#` is the comment leader in some Unix shells (e.g. zsh, bash) and that would make this difficult to use as you would need to do `swift explain '#StrictMemorySafety'`. ---
**Author:** ![Douglas\_Gregor](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/douglas_gregor/32/1362_2.png) [@Douglas\_Gregor](https://forums.swift.org/u/Douglas_Gregor)\ **Post date:** [March 4, 2025, 6:28am UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/16 "2025-03-04T06:28:59Z")
> [@owenv](#): > > The local vs CI/remote builds discrepancy is largely why I was originally thinking of exposing a swift-explain executable back in the day - assuming identifiers are stable and the user has a toolchain at least as new as the one which produced a log, it would allow users to just copy and paste a command to access the docs. I think it's reasonable to have `swift explain ` for any of these names, which could do the Markdown rendering. That said, I still like the "one click" approach of having hyperlinks to the documentation files, but perhaps that makes the most sense in an IDE vs. on the command line. > [@owenv](#): > > If we did that, I think the printed output could look something like: > > ```swift > [#StrictMemorySafety]: swift explain #StrictMemorySafety > > ``` This feels like it would get really verbose if there were more than 2 or so, but I suppose that's okay. > [@owenv](#): > > It might be worth moving the notes to a docc catalog even if it's a little different from the traditional use cases. Some structure could be useful for publishing on [swift.org](http://swift.org) as well. I don't have strong opinions on DocC catalog vs. something simpler and purpose-built. Looking at the educational note infrastructure, I think I'd like to simplify down to say that we can have at most one document associated with a given diagnostic. That way, we don't end up with a pile of references for a given diagnostic, an everything can be simplified down to "zero or one category with its optional documentation." Doug ---
**Author:** ![Douglas\_Gregor](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/douglas_gregor/32/1362_2.png) [@Douglas\_Gregor](https://forums.swift.org/u/Douglas_Gregor)\ **Post date:** [March 4, 2025, 5:41pm UTC](https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023/17 "2025-03-04T17:41:44Z")
> [@Joseph\_Heck](#): > > The second is that today it (docc rendering) requires the JavaScript app to be running to see the content, since it's rendering on the fly from the archive. That makes consuming this from arbitrary developer tooling (Xcode to visual studio code to NeoVIM or emacs) far more challenging. > > That said, if this is an argument in favor of getting static-html-output support into DocC tooling to make it easy to create single or sets of static HTML pages with content, count me in on that! I certainly interpret this as an argument for static-html-output support for DocC tooling. We don't need a lot for this documentation: static HTML with some decent Swift syntax highlighting that we can bundle in the toolchain. We could probably build something like this on top of swift-markdown fairly easily, but I'd rather not duplicate effort if static-html-output support is on the table for DocC. Doug