# RFC: Add category & documentation URL to DiagnosticMessage

**URL:** <https://forums.swift.org/t/rfc-add-category-documentation-url-to-diagnosticmessage/78276>\
**Category:** Swift Syntax\
**Created:** [March 4, 2025, 5:59pm UTC](https://forums.swift.org/t/rfc-add-category-documentation-url-to-diagnosticmessage/78276 "2025-03-04T17:59:55Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**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:59pm UTC](https://forums.swift.org/t/rfc-add-category-documentation-url-to-diagnosticmessage/78276/1 "2025-03-04T17:59:55Z")

</div>

This adds an optional category property to `DiagnosticMessage`, which is used to provide more information about diagnostics.  
**Link to PR** : [https://github.com/swiftlang/swift-syntax/pull/2981](https://github.com/swiftlang/swift-syntax/pull/2981)

## Swift interface

Introduces a new `DiagnosticCategory` type:

```swift
/// 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:

```swift
/// 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

---

<div class="post-metadata">

**Author:** ![grynspan](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/grynspan/32/15315_2.png) [@grynspan](https://forums.swift.org/u/grynspan)\
**Post date:** [March 4, 2025, 7:05pm UTC](https://forums.swift.org/t/rfc-add-category-documentation-url-to-diagnosticmessage/78276/2 "2025-03-04T19:05:06Z")

</div>

~~Will there be a default implementation for the new protocol requirement?~~ Never mind, found it.

---

<div class="post-metadata">

**Author:** ![ahoppen](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/ahoppen/32/36046_2.png) [@ahoppen](https://forums.swift.org/u/ahoppen)\
**Post date:** [March 5, 2025, 9:57pm UTC](https://forums.swift.org/t/rfc-add-category-documentation-url-to-diagnosticmessage/78276/3 "2025-03-05T21:57:40Z")

</div>

Thank you. This looks like a good addition to me.