I've been thinking about this a bit more over the past couple days and I think we can break most of the improvements proposed in this thread into one of the following categories:
-
More detailed educational content in errors. For example, an extra paragraph explaining why a protocol type cannot be used as a generic constraint
-
More detailed annotations of a user's code when they encounter an error. Instead of producing an error and collection of notes, produce a unified code snippet with more detailed annotations pointing out the problem.
-
A better way of discussing/documenting diagnostics on external platforms. This is the issue naming diagnostics tries to solve.
What I originally pitched was a combination of 1 and 3 which would make it harder to achieve 2 in the long run. While I think 2 is going to be the hardest item to accomplish, I think it's pretty clear at this point we shouldn't just give up on making improvements in this area. If we build 1 & 2, 3 becomes less important because it's no longer a necessary part of the compiler tooling. However, it's still potentially useful for indexing educational content if we host it on the web, and for use by external tooling/q&a/platforms.
I'd like to propose a new "roadmap" which should hopefully allow us to tackle all of these issues incrementally:
-
Introduce a new compiler flag,
-enable-descriptive-diagnostics. This will gate all of the features described below, and can remain a private frontend option until enough has been accomplished to officially ship the improvements. -
If the flag is passed, the compiler will produce a "descriptive" annotated code snippet rather than an error and list of notes. This will follow the approach @xedin describes above. If a particular diagnostic hasn't been migrated yet, fallback to the current system.
-
If the flag is passed, also check to see whether the diagnostic has educational documentation associated with it. If so, print this before/after the message. By separating educational content which isn't specific to the context from annotations, we can make it easier to make incremental improvements to a diagnostic because this content could be worked on by contributors who are less comfortable writing C++. By putting this behind a flag, we can also expose it in the terminal, through SourceKit, etc. without requiring a
swift-explainlookup step. -
(Maybe) Introduce public diagnostic names. Even if they're not necessary to interact with the compiler, they might still be useful for looking things up on Google/StackOverflow. They could also be used to index the educational content if we wanted to host it on Swift.org. The question here is, would they be worth the additional maintenance burden they create?
Apologies for the long post, I'd be interested in hearing everyone's thoughts on this! Once some of the details are sorted out, I plan on submitting a PR to add the -enable-descriptive-diagnostics flag and another to submit a formalized roadmap document. I expect actually accomplishing everything listed above will be a very long-term effort, but a lot of these improvements are interconnected and I think it makes sense to properly establish the long-term vision.