Add comment clarifying rationale behind ResolvedTopicReference's immutability

Author: ethan-kusters

Sources/SwiftDocC/Model/Identifier.swift

@@ -74,7 +74,16 @@ public enum TopicReferenceResolutionResult: Hashable, CustomStringConvertible {
 /// (i.e. there is a file on disk or data in memory ready to be
 /// recalled at any time).
 ///
-/// > Important: This type has copy-on-write semantics.
+/// ## Implementation Details
+///
+/// `ResolvedTopicReference` is effectively a wrapper around Foundation's `URL` and,
+/// because of this, it exposes an API very similar to `URL` and does not allow direct modification
+/// of its properties. This immutability brings performance benefits and communicates with
+/// user's of the API that doing something like adding a path component
+/// is a potentially expensive operation, just as it is on `URL`.
+///
+/// > Important: This type has copy-on-write semantics and wraps an underlying class to store
+/// > its data.
 public struct ResolvedTopicReference: Hashable, Codable, Equatable, CustomStringConvertible {
     typealias ReferenceBundleIdentifier = String
     typealias ReferenceKey = String