This adds an optional category property to DiagnosticMessage, which is used to provide more information about diagnostics.
Link to PR: Add an optional diagnostic category to diagnostics by DougGregor · Pull Request #2981 · swiftlang/swift-syntax · GitHub
Swift interface
Introduces a new DiagnosticCategory type:
/// Describes a category of diagnostics, which covers a set of related
/// diagnostics that can share documentation.
public struct DiagnosticCategory: Sendable, Hashable {
/// Name that identifies the category, e.g., StrictMemorySafety.
public let name: String
/// URL providing documentation documentation for this category.
public let documentationURL: String?
public init(name: String, documentationURL: String?) {
self.name = name
self.documentationURL = documentationURL
}
}
and extends DiagnosticMessage with a category property:
/// The category that this diagnostic belongs in.
var category: DiagnosticCategory? { get }
There's also a default implementation of category that returns nil, so we don't break existing types that conform to DiagnosticMessage.
The Swift compiler's diagnostics has had a category field for a long time, but it wasn't really used for much of anything, so we didn't bring it into the swift-syntax notion of a diagnostic. With more focus on diagnostic groups and educational notes in the compiler, we want to model this concept for swift-syntax as well. The combination of a single category (which doubles as the diagnostic group name for -Wwarning/-Werror flags) plus a documentation URL lets us communicate additional information to help users.
Doug