Improve documentation of SyntaxProtocol.tracked and write entry in release notes

Author: ahoppen

Release Notes/601.md

@@ -6,7 +6,7 @@
   - Description: Allows retrieving the represented literal value when valid.
   - Issue: https://github.com/apple/swift-syntax/issues/405
   - Pull Request: https://github.com/apple/swift-syntax/pull/2605
-    
+
 - `SyntaxProtocol` now has a method `ancestorOrSelf`.
   - Description: Returns the node or the first ancestor that satisfies `condition`.
   - Pull Request: https://github.com/swiftlang/swift-syntax/pull/2696
@@ -19,6 +19,11 @@
   - Description: This new library provides facilities for evaluating `#if` conditions and determining which regions of a syntax tree are active according to a given build configuration.
   - Pull Request: https://github.com/swiftlang/swift-syntax/pull/1816
 
+- `SyntaxProtocol.tracked` / `SyntaxProtocol.originalNode(in:)`
+  - Description: `tracked` enables node tracking of a tree. For every tree derived from a tracked tree, `originalNode(in:)` returns the original node in the tracked tree. This allows clients to e.g. get the original location of a node in a source file after a tree has been modified.
+  - Issue: rdar://112679655
+  - Pull Request: https://github.com/apple/swift-syntax/pull/2118
+
 ## API Behavior Changes
 
 - `SyntaxProtocol.trimmed` detaches the node
@@ -38,7 +43,7 @@
   - Description: Allows retrieving the radix value from the `literal.text`.
   - Issue: https://github.com/apple/swift-syntax/issues/405
   - Pull Request: https://github.com/apple/swift-syntax/pull/2605
-  
+
 - `FixIt.Change` gained a new case `replaceChild(data:)`.
   - Description: The new case covers the replacement of a child node with another node.
   - Issue: https://github.com/swiftlang/swift-syntax/issues/2205

Sources/SwiftSyntax/SyntaxTracking.swift

@@ -278,18 +278,39 @@ class IndexInTreeFinder: SyntaxAnyVisitor {
 }
 
 extension SyntaxProtocol {
-  /// The same ``Syntax`` but with tracking enabled in the entire tree.
+  /// Start tracking this syntax tree as the original tree for all trees derived
+  /// from it.
   ///
-  /// All syntax nodes derived from this will be able to find their
-  /// corresponding location in this original tree.
+  /// All syntax nodes derived from the returned, tracked, tree will be able to
+  /// find the corresponding node in the original tree by calling
+  /// ``SyntaxProtocol/originalNode(in:)``.
+  ///
+  /// Derived nodes are
+  ///  - Nodes that contain a node from this tree as a subtree.
+  ///  - Nodes that resulted from modification of a node in this tree (e.g.
+  ///    modification of a child node or insertion of an element into a
+  ///    collection).
+  ///  - Detached subtrees of this tree (see ``SyntaxProtocol/detached``).
+  ///
+  /// Node tracking is not enabled by default because maintaining the mapping
+  /// back to the tracked tree has a performance cost that.
+  ///
+  /// A tree can only track a single original tree. I.e. it is not possible to
+  /// create a node that has one child in tracked tree A and another child in
+  /// tracked tree B. In practice, this should seldom pose an issue because the
+  /// most common use case is to mark the tree obtained from a file on disk as
+  /// the tracked tree and trees from separate source files will rarely be
+  /// merged.
   ///
+  /// - SeeAlso: ``SyntaxProtocol/originalNode(in:)``
   /// - Complexity: O(number of ancestors)
   public var tracked: Self {
     return Syntax(self).tracked.cast(Self.self)
   }
 
   /// If this syntax node is tracking `originalTree` and this node originated
-  /// in that tree, return the corresponding corresponding node in `originalTree`.
+  /// from that tree, return the corresponding corresponding node in
+  /// `originalTree`.
   ///
   /// The original node will have the same structure as this node but the parent
   /// might be different since it's anchored in `originalTree`.