From 66435cb0cff9549990bce8fcfe7576321fbe0839 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 11 Nov 2024 13:14:32 +0100
Subject: [PATCH 01/12] Indent table markup for readability

---
 .../linking-to-symbols-and-other-content.md          | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index 6714bd6f42..83602374c5 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -6,12 +6,12 @@ Facilitate navigation between pages using links.
 
 DocC supports the following link types to enable navigation between pages:
 
-| Type | Usage |
-| --- | --- |
-| Symbol | Links to a symbol's reference page in your documentation. |
-| Article | Links to an article or API collection in your documentation catalog. |
-| Tutorial | Links to a tutorial in your documentation catalog. |
-| Web | Links to an external URL. |
+| Type     | Usage 
+| -------- | ----- 
+| Symbol   | Links to a symbol's reference page in your documentation.
+| Article  | Links to an article or API collection in your documentation catalog.
+| Tutorial | Links to a tutorial in your documentation catalog.
+| Web      | Links to an external URL.
 
 ### Navigate to a Symbol
 

From 44c042340febabda2809b60cb1eee940a1def3b7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 11 Nov 2024 17:26:32 +0100
Subject: [PATCH 02/12] Add more details about how relative symbol links works

---
 .../linking-to-symbols-and-other-content.md   | 60 ++++++++++++++++---
 1 file changed, 51 insertions(+), 9 deletions(-)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index 83602374c5..641f6a25b8 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -15,23 +15,65 @@ DocC supports the following link types to enable navigation between pages:
 
 ### Navigate to a Symbol
 
-To add a link to a symbol, wrap the symbol's name in a set of double backticks 
-(\`\`).
+To add a link to a symbol, wrap the symbol's name in a set of double backticks (\`\`):
 
 ```markdown
-``SlothCreator``
+``Sloth``
 ```
 
-For nested symbols, include the path to the symbol in the link.
+For member symbols or nested types, include the path to the symbol in the link:
 
 ```markdown
-``SlothCreator/Sloth/eat(_:quantity:)``
+``Sloth/eat(_:quantity:)``
+``Sloth/Food``
 ```
 
-DocC resolves symbol links relative to the context they appear in. For example, 
-a symbol link that appears inline in the `Sloth` class, and targets a 
-symbol in that class, can omit the `SlothCreator/Sloth/` portion of the symbol 
-path.
+DocC resolves symbol links relative to the context that the link appears in.
+This allows links in a type's documentation comment to omit the type's name from the symbol path when referring to its members.
+For example, in the `Sloth` structure below, the `init(name:color:power:)` symbol link in the structure's documentation comment can omit the `Sloth/` portion of the symbol path:
+
+```swift
+/// ...
+/// You can create a sloth using ``init(name:color:power:)``.
+public struct Sloth { //           ╰──────────┬──────────╯
+    /// ...           //                      ╰─────refers-to────╮
+    public init(name: String, color: Color, power: Power) { // ◁─╯ 
+        /* ... */ 
+    }         
+}
+```
+
+If DocC can't resolve a link in the current context, it expands the search to the containing scope.
+This allows links from one member to another member of the same type to omit the containing type's name from the symbol path.
+For example, in the `Sloth` structure below, the `eat(_:quantity:)` symbol link in the `energyLevel` property's documentation comment 
+can omit the `Sloth/` portion of the symbol path:
+
+```swift
+/// ...
+public struct Sloth {
+    /// ... 
+    /// Restore the sloth's energy using ``eat(_:quantity:)``.
+    public var energyLevel = 10 //         ╰───────┬──────╯       
+                                //                 │ 
+    /// ...                     //                 ╰──────refers-to─────╮
+    public mutating func eat(_ food: Food, quantity: Int) -> Int { // ◁─╯ 
+        /* ... */
+    }
+}
+```
+
+> Note:
+If you prefer absolute symbol links you can prefix the symbol path with a leading slash followed by the name of the module that symbol belongs:
+>
+> ```markdown
+> ``/SlothCreator/Sloth``
+> ``/SlothCreator/Sloth/eat(_:quantity:)``
+> ``/SlothCreator/Sloth/Food``
+> ```
+>
+> DocC resolves absolute symbol links from the module's scope instead of the context that the link appears in.  
+
+#### Ambiguous Symbol Links
 
 In some cases, a symbol's path isn't unique, such as with overloaded methods in 
 Swift. For example, consider the `Sloth` structure, which has multiple 

From a928b6123aa64d5d57ac51cfb23aac04b2ad8c05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 11 Nov 2024 17:54:48 +0100
Subject: [PATCH 03/12] Move examples about unambiguous links before "Ambiguous
 Symbol Links" section.

---
 .../linking-to-symbols-and-other-content.md   | 75 +++++++++++--------
 1 file changed, 44 insertions(+), 31 deletions(-)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index 641f6a25b8..100817a8e9 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -73,6 +73,50 @@ If you prefer absolute symbol links you can prefix the symbol path with a leadin
 >
 > DocC resolves absolute symbol links from the module's scope instead of the context that the link appears in.  
 
+Symbol paths are case-sensitive, meaning that symbols with the same name in different text casing are unambiguous.
+For example, consider a `Sloth` structure with both a `color` property and a `Color` enumeration type:
+
+```swift
+public struct Sloth {
+    public var color: Color 
+
+    public enum Color {
+        /* ... */
+    }
+}
+```
+
+A `Sloth/color` symbol link unambiguously refers to the `color` property and a `Sloth/Color` symbol link unambiguously refers to the inner `Color` type.
+
+#### Symbols with Multiple Language Representations
+
+Symbol links to symbols that have representations in more than one programming language can use symbol paths in either source language. 
+For example, consider a `Sloth` class with `@objc` attributes:
+
+```swift
+@objc(TLASloth) public class Sloth: NSObject {
+    @objc public init(name: String, color: Color, power: Power) {
+        self.name = name
+        self.color = color
+        self.power = power
+    }
+}
+```
+
+You can write a symbol link to the Sloth initializer using the symbol path in either source language:
+
+**Swift name**
+
+```markdown
+``Sloth/init(name:color:power:)``
+```
+
+**Objective-C name**
+
+```markdown
+``TLASloth/initWithName:color:power:``
+```
+
 #### Ambiguous Symbol Links
 
 In some cases, a symbol's path isn't unique, such as with overloaded methods in 
@@ -173,37 +217,6 @@ Symbol type suffixes can include a source language identifier prefix — for
 example,  `-swift.enum` instead of `-enum`. However, the language 
 identifier doesn't disambiguate the link.
 
-Symbol paths are case-sensitive, meaning that symbols with the same name in
-different text casing don't need disambiguation. 
-
-Symbols that have representations in both Swift and Objective-C can use
-symbol paths in either source language. For example, consider a `Sloth` 
-class with `@objc` attributes:
-
-```swift
-@objc(TLASloth) public class Sloth: NSObject {
-    @objc public init(name: String, color: Color, power: Power) {
-        self.name = name
-        self.color = color
-        self.power = power
-    }
-}
-```
-
-You can write a symbol link to the Sloth initializer using the symbol path in either source language.
-
-**Swift name**
-
-```markdown
-``Sloth/init(name:color:power:)``
-```
-
-**Objective-C name**
-
-```markdown
-``TLASloth/initWithName:color:power:``
-```
-
 ### Navigate to an Article
 
 To add a link to an article, use the less-than symbol (`<`), the `doc` keyword, 

From 9fcc3cb4e922844e945c19c8fc01c2bd69596b74 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 11 Nov 2024 17:58:38 +0100
Subject: [PATCH 04/12] Reorder list of supported disambiguation symbol types

---
 .../linking-to-symbols-and-other-content.md            | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index 100817a8e9..84212497b8 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -196,19 +196,19 @@ DocC supports the following symbol types for use in symbol links:
 | Enumeration       | `-enum`           |
 | Enumeration case  | `-enum.case`      |
 | Protocol          | `-protocol`       |
-| Operator          | `-func.op`        |
 | Typealias         | `-typealias`      |
-| Function          | `-func`           |
 | Structure         | `-struct`         |
 | Class             | `-class`          |
+| Function          | `-func`           |
+| Operator          | `-func.op`        |
+| Property          | `-property`       |
 | Type property     | `-type.property`  |
+| Method            | `-method`         |
 | Type method       | `-type.method`    |
+| Subscript         | `-subscript`      |
 | Type subscript    | `-type.subscript` |
-| Property          | `-property`       |
 | Initializer       | `-init`           |
 | Deinitializer     | `-deinit`         |
-| Method            | `-method`         |
-| Subscript         | `-subscript`      |
 | Instance variable | `-ivar`           |
 | Macro             | `-macro`          |
 | Module            | `-module`         |

From 42a4cd02b6223a67a4a36ff9ce2f86d7e40a35d9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 11 Nov 2024 18:02:43 +0100
Subject: [PATCH 05/12] Add missing supported disambiguation symbol types

---
 .../linking-to-symbols-and-other-content.md              | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index 84212497b8..df3b70722d 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -197,6 +197,7 @@ DocC supports the following symbol types for use in symbol links:
 | Enumeration case  | `-enum.case`      |
 | Protocol          | `-protocol`       |
 | Typealias         | `-typealias`      |
+| Associated Type   | `-associatedtype` |
 | Structure         | `-struct`         |
 | Class             | `-class`          |
 | Function          | `-func`           |
@@ -209,9 +210,17 @@ DocC supports the following symbol types for use in symbol links:
 | Type subscript    | `-type.subscript` |
 | Initializer       | `-init`           |
 | Deinitializer     | `-deinit`         |
+| Global variable   | `-var`            |
 | Instance variable | `-ivar`           |
 | Macro             | `-macro`          |
 | Module            | `-module`         |
+| Namespace         | `-namespace`      |
+| HTTP Request      | `-httpRequest`    |
+| HTTP Parameter    | `-httpParameter`  |
+| HTTP Response     | `-httpResponse`   |
+| HTTPBody          | `-httpBody`       |
+| Dictionary        | `-dictionary`     |
+| Dictionary Key    | `-dictionaryKey`  |
 
 Symbol type suffixes can include a source language identifier prefix — for 
 example,  `-swift.enum` instead of `-enum`. However, the language 

From 1d121b72e82db84dd40358685d298f3b2bd16045 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Mon, 11 Nov 2024 18:45:09 +0100
Subject: [PATCH 06/12] Move the symbol type disambiguation example above the
 hash disambiguation example

---
 .../linking-to-symbols-and-other-content.md   | 94 +++++++++----------
 1 file changed, 46 insertions(+), 48 deletions(-)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index df3b70722d..d5049b015e 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -119,47 +119,9 @@ You can write a symbol link to the Sloth initializer using the symbol path in ei
 
 #### Ambiguous Symbol Links
 
-In some cases, a symbol's path isn't unique, such as with overloaded methods in 
-Swift. For example, consider the `Sloth` structure, which has multiple 
-`update(_:)` methods:
-
-```swift
-/// Updates the sloth's power.
-///
-/// - Parameter power: The sloth's new power.
-mutating public func update(_ power: Power) {
-    self.power = power
-}
-
-/// Updates the sloth's energy level.
-///
-/// - Parameter energyLevel: The sloth's new energy level.
-mutating public func update(_ energyLevel: Int) {
-    self.energyLevel = energyLevel
-}
-```
-
-Both methods have an identical symbol path of `SlothCreator/Sloth/update(_:)`. 
-In this scenario, and to ensure uniqueness, DocC uses the symbol's unique 
-identifier instead of its name to disambiguate. DocC's warnings about ambiguous
-symbol links suggests one disambiguation for each of the symbols that match the
-ambiguous symbol path.
-
-```markdown
-### Updating Sloths
-- ``Sloth/update(_:)-4ko57``
-- ``Sloth/update(_:)-jixx``
-```
-
-In the example above, both symbols are functions, so you need the unique 
-identifiers to disambiguate the `Sloth/update(_:)` link. 
-
-Unique identifiers aren't the only way to disambiguate symbol links. If a symbol
-has a different type from the other symbols with the same symbol path, you can 
-use that symbol's type suffix to disambiguate the link and make the link refer 
-to that symbol. For example, consider a `Color` structure with `red`, `green`, 
-and `blue` properties for color components and static properties for a handful 
-of predefined color values:
+In some cases a symbol's path isn't unique.
+This makes it ambiguous what specific symbol a symbol link refers to. 
+For example, consider a `Color` structure with `red`, `green`, and `blue` properties for color components and static properties for a handful of predefined color values:
 
 ```swift
 public struct Color {
@@ -173,9 +135,8 @@ extension Color {
 }
 ```
 
-Both the `red` property and the `red` static property have a symbol path of 
-`Color/red`. Because these are different types of symbols you can disambiguate 
-`Color/red` with symbol type suffixes instead of the symbols' unique identifiers.
+Both the `red` property and the `red` static property have a symbol path of `Color/red`. 
+Because these are different types of symbols you can disambiguate `Color/red` with a suffix indicating the symbol's type.
 
 The following example shows a symbol link to the `red` property:
 
@@ -189,7 +150,7 @@ The following example shows a symbol link to the `red` static property:
 ``Color/red-type.property``
 ```
 
-DocC supports the following symbol types for use in symbol links:
+DocC supports the following symbol types as disambiguation in symbol links:
 
 | Symbol type       | Suffix            |
 |-------------------|-------------------|
@@ -222,9 +183,46 @@ DocC supports the following symbol types for use in symbol links:
 | Dictionary        | `-dictionary`     |
 | Dictionary Key    | `-dictionaryKey`  |
 
-Symbol type suffixes can include a source language identifier prefix — for 
-example,  `-swift.enum` instead of `-enum`. However, the language 
-identifier doesn't disambiguate the link.
+You can discover these symbol type suffixes from DocC's warnings about ambiguous symbol links.
+DocC suggests one disambiguation for each of the symbols that match the ambiguous symbol path.
+
+Symbol type suffixes can include a source language identifier prefix---for example, `-swift.enum` instead of `-enum`. 
+However, the language identifier doesn't disambiguate the link.
+
+
+In the example above, both symbols that match the ambiguous symbol path were the same type of symbol.
+If the symbols that match the ambiguous symbol path have are the same type of symbol, 
+such as with overloaded methods in Swift, a symbol type suffix won't disambiguate the link.
+
+For example, consider the `Sloth` structure---from the SlothCreator example---which has two different `update(_:)` methods:
+
+```swift
+/// Updates the sloth's power.
+///
+/// - Parameter power: The sloth's new power.
+mutating public func update(_ power: Power) {
+    self.power = power
+}
+
+/// Updates the sloth's energy level.
+///
+/// - Parameter energyLevel: The sloth's new energy level.
+mutating public func update(_ energyLevel: Int) {
+    self.energyLevel = energyLevel
+}
+```
+
+Both methods have an identical symbol path of `SlothCreator/Sloth/update(_:)`. 
+In this scenario, DocC uses a short hash of each symbol's unique identifier to disambiguate the symbol link. 
+You can discover these hashes from DocC's warnings about ambiguous symbol links.
+The following example shows a topic group with disambiguated symbol links to both `Sloth/update(_:)` methods:
+
+```markdown
+### Updating Sloths
+
+- ``Sloth/update(_:)-4ko57``
+- ``Sloth/update(_:)-jixx``
+```
 
 ### Navigate to an Article
 

From 6675b6c1450391c4bf7fe452865aeaeb2a9b7939 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 13 Nov 2024 16:43:49 +0100
Subject: [PATCH 07/12] Update `Sloth/update(_:)` example to describe type
 disambiguation

rdar://136207820
---
 .../linking-to-symbols-and-other-content.md   | 22 +++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index d5049b015e..951b9cb952 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -213,13 +213,31 @@ mutating public func update(_ energyLevel: Int) {
 ```
 
 Both methods have an identical symbol path of `SlothCreator/Sloth/update(_:)`. 
-In this scenario, DocC uses a short hash of each symbol's unique identifier to disambiguate the symbol link. 
-You can discover these hashes from DocC's warnings about ambiguous symbol links.
+In this scenario, DocC uses information from the symbols' type signatures to disambiguate.
+In this example there's only one parameter and its type is `Power` for the first overload and `Int` for the second overload. 
+DocC uses this parameter type information to suggest adding `(Power)` and `(Int)` to disambiguate each respective overload.
+
 The following example shows a topic group with disambiguated symbol links to both `Sloth/update(_:)` methods:
 
 ```markdown
 ### Updating Sloths
 
+- ``Sloth/update(_:)-(Power)``
+- ``Sloth/update(_:)-(Int)``
+```
+
+> Earlier Versions:
+> Before Swift-DocC 6.1, disambiguation using parameter types or return types isn't supported.
+
+If DocC can't disambiguate the symbol link using either a symbol type suffix or a combination parameter type names and return type names, 
+it will fall back to using a short hash of each symbol's unique identifier to disambiguate the symbol link. 
+You can discover these hashes from DocC's warnings about ambiguous symbol links.
+The following example shows the same topic group with symbol links to both `Sloth/update(_:)` methods as before, 
+but using each symbols unique identifier hash for disambiguation:
+
+```markdown
+### Updating Sloths
+
 - ``Sloth/update(_:)-4ko57``
 - ``Sloth/update(_:)-jixx``
 ```

From a5bcf424df827f80208ebd5e9609e667adfa3458 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 13 Nov 2024 16:44:44 +0100
Subject: [PATCH 08/12] Add another more complicated type disambiguation
 example

rdar://136207820
---
 .../linking-to-symbols-and-other-content.md   | 45 +++++++++++++++++--
 1 file changed, 41 insertions(+), 4 deletions(-)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index 951b9cb952..23bf8ee68b 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -226,20 +226,57 @@ The following example shows a topic group with disambiguated symbol links to bot
 - ``Sloth/update(_:)-(Int)``
 ```
 
+If there are more overloads with more parameters and return values, 
+DocC may suggest a combination of parameter types and return value types to uniquely disambiguate each overload. 
+For example consider a hypothetical weather service with these three overloads---with different parameter types and different return types---for a hypothetical `forecast(for:at:)` method:
+
+```swift
+public func forecast(for days: DateInterval, at location: Location) -> HourByHourForecast     { /* ... */ }
+public func forecast(for day:  Date,         at location: Location) -> MinuteByMinuteForecast { /* ... */ }
+public func forecast(for day:  Date,         at location: Location) -> HourByHourForecast     { /* ... */ }
+```
+
+The first overload is the only one with where the first parameter has a `DateInterval` type. 
+The second parameter type isn't necessary to disambiguate the overload, and is the same in all three overloads, 
+so DocC suggests to add `(DateInterval,_)` to disambiguate the it.
+
+The second overload is the only one with where the return value has a `MinuteByMinuteForecast` type, 
+so DocC suggests to add `‑>MinuteByMinuteForecast` to disambiguate the it.
+
+The third overload has the same parameter types as the second overload and the same return value as the first overload, 
+so DocC neither parameter types or return types alone can uniquely disambiguate this overload.
+In this scenario, DocC considers a combination of parameter types and return types to disambiguate the overload.
+The first parameter type is different from the first overload and the return type is different from the second overload.
+Together this information uniquely disambiguates the third overload, 
+so DocC suggests to add `(Date,_)‑>HourByHourForecast` to disambiguate the it.
+
+You can discover the minimal combination of parameter types and return types for each overload from DocC's warnings about ambiguous symbol links.
+
+The following example shows a topic group with disambiguated symbol links to the three `forecast(for:at:)` methods from before:
+
+```markdown
+### Requesting weather forecasts
+
+- ``forecast(for:at:)-(DateInterval,_)``
+- ``forecast(for:at:)->MinuteByMinuteForecast``
+- ``forecast(for:at:)->(Date,_)->HourByHourForecast``
+```
+
 > Earlier Versions:
 > Before Swift-DocC 6.1, disambiguation using parameter types or return types isn't supported.
 
 If DocC can't disambiguate the symbol link using either a symbol type suffix or a combination parameter type names and return type names, 
 it will fall back to using a short hash of each symbol's unique identifier to disambiguate the symbol link. 
 You can discover these hashes from DocC's warnings about ambiguous symbol links.
-The following example shows the same topic group with symbol links to both `Sloth/update(_:)` methods as before, 
+The following example shows the same topic group with symbol links to the three `forecast(for:at:)` methods as before, 
 but using each symbols unique identifier hash for disambiguation:
 
 ```markdown
-### Updating Sloths
+### Requesting weather forecasts
 
-- ``Sloth/update(_:)-4ko57``
-- ``Sloth/update(_:)-jixx``
+- ``forecast(for:at:)-3brnk``
+- ``forecast(for:at:)-4gcpg``
+- ``forecast(for:at:)-7f3u``
 ```
 
 ### Navigate to an Article

From 1489927f84152b73e755e4ed361400cdfa779d7a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Wed, 13 Nov 2024 16:53:13 +0100
Subject: [PATCH 09/12] Minor refinements to the new documentation

---
 .../linking-to-symbols-and-other-content.md   | 23 +++++++++----------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index 23bf8ee68b..7472edfc93 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -15,13 +15,13 @@ DocC supports the following link types to enable navigation between pages:
 
 ### Navigate to a Symbol
 
-To add a link to a symbol, wrap the symbol's name in a set of double backticks (\`\`):
+To add a link to a symbol in your module, wrap the symbol's name in a set of double backticks (\`\`):
 
 ```markdown
 ``Sloth``
 ```
 
-For member symbols or nested types, include the path to the symbol in the link:
+For links to member symbols or nested types, include the path to the symbol in the link:
 
 ```markdown
 ``Sloth/eat(_:quantity:)``
@@ -30,7 +30,7 @@ For member symbols or nested types, include the path to the symbol in the link:
 
 DocC resolves symbol links relative to the context that the link appears in.
 This allows links in a type's documentation comment to omit the type's name from the symbol path when referring to its members.
-For example, in the `Sloth` structure below, the `init(name:color:power:)` symbol link in the structure's documentation comment can omit the `Sloth/` portion of the symbol path:
+For example, in the `Sloth` structure below, the `init(name:color:power:)` symbol link omits the `Sloth/` portion of the symbol path:
 
 ```swift
 /// ...
@@ -43,10 +43,10 @@ public struct Sloth { //           ╰──────────┬───
 }
 ```
 
-If DocC can't resolve a link in the current context, it expands the search to the containing scope.
+If DocC can't resolve a link in the current context, it gradually expands the search to the containing scope.
 This allows links from one member to another member of the same type to omit the containing type's name from the symbol path.
-For example, in the `Sloth` structure below, the `eat(_:quantity:)` symbol link in the `energyLevel` property's documentation comment 
-can omit the `Sloth/` portion of the symbol path:
+For example, in the `Sloth` structure below, 
+the `eat(_:quantity:)` symbol link in the `energyLevel` property's documentation comment omits the `Sloth/` portion of the symbol path:
 
 ```swift
 /// ...
@@ -86,7 +86,7 @@ public struct Sloth {
 }
 ```
 
-A `Sloth/color` symbol link unambiguously refers to the `color` property and a `Sloth/Color` symbol link unambiguously refers to the inner `Color` type.
+A ` ``Sloth/color`` ` symbol link unambiguously refers to the `color` property and a ` ``Sloth/Color`` ` symbol link unambiguously refers to the inner `Color` type.
 
 #### Symbols with Multiple Language Representations
 
@@ -136,7 +136,7 @@ extension Color {
 ```
 
 Both the `red` property and the `red` static property have a symbol path of `Color/red`. 
-Because these are different types of symbols you can disambiguate `Color/red` with a suffix indicating the symbol's type.
+Because these are different types of symbols you can disambiguate ` ``Color/red`` ` with a suffix indicating the symbol's type.
 
 The following example shows a symbol link to the `red` property:
 
@@ -190,10 +190,10 @@ Symbol type suffixes can include a source language identifier prefix---for examp
 However, the language identifier doesn't disambiguate the link.
 
 
-In the example above, both symbols that match the ambiguous symbol path were the same type of symbol.
+In the example above, both symbols that match the ambiguous symbol path were different types of symbol.
 If the symbols that match the ambiguous symbol path have are the same type of symbol, 
 such as with overloaded methods in Swift, a symbol type suffix won't disambiguate the link.
-
+In this scenario, DocC uses information from the symbols' type signatures to disambiguate.
 For example, consider the `Sloth` structure---from the SlothCreator example---which has two different `update(_:)` methods:
 
 ```swift
@@ -213,7 +213,6 @@ mutating public func update(_ energyLevel: Int) {
 ```
 
 Both methods have an identical symbol path of `SlothCreator/Sloth/update(_:)`. 
-In this scenario, DocC uses information from the symbols' type signatures to disambiguate.
 In this example there's only one parameter and its type is `Power` for the first overload and `Int` for the second overload. 
 DocC uses this parameter type information to suggest adding `(Power)` and `(Int)` to disambiguate each respective overload.
 
@@ -228,7 +227,7 @@ The following example shows a topic group with disambiguated symbol links to bot
 
 If there are more overloads with more parameters and return values, 
 DocC may suggest a combination of parameter types and return value types to uniquely disambiguate each overload. 
-For example consider a hypothetical weather service with these three overloads---with different parameter types and different return types---for a hypothetical `forecast(for:at:)` method:
+For example consider a hypothetical weather service with these three overloads---with different parameter types and different return types---for a `forecast(for:at:)` method:
 
 ```swift
 public func forecast(for days: DateInterval, at location: Location) -> HourByHourForecast     { /* ... */ }

From d06d62e9473fcf51ca3760c9025b9497b33ead36 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 5 Dec 2024 15:25:41 +0100
Subject: [PATCH 10/12] Fix 3 incomplete sentences in the new documentation

---
 .../linking-to-symbols-and-other-content.md                 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index a03c61eca5..77ec5a9d80 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -237,17 +237,17 @@ public func forecast(for day:  Date,         at location: Location) -> HourByHou
 
 The first overload is the only one with where the first parameter has a `DateInterval` type. 
 The second parameter type isn't necessary to disambiguate the overload, and is the same in all three overloads, 
-so DocC suggests to add `(DateInterval,_)` to disambiguate the it.
+so DocC suggests to add `(DateInterval,_)` to disambiguate the first overload.
 
 The second overload is the only one with where the return value has a `MinuteByMinuteForecast` type, 
-so DocC suggests to add `‑>MinuteByMinuteForecast` to disambiguate the it.
+so DocC suggests to add `‑>MinuteByMinuteForecast` to disambiguate the second overload.
 
 The third overload has the same parameter types as the second overload and the same return value as the first overload, 
 so DocC neither parameter types or return types alone can uniquely disambiguate this overload.
 In this scenario, DocC considers a combination of parameter types and return types to disambiguate the overload.
 The first parameter type is different from the first overload and the return type is different from the second overload.
 Together this information uniquely disambiguates the third overload, 
-so DocC suggests to add `(Date,_)‑>HourByHourForecast` to disambiguate the it.
+so DocC suggests to add `(Date,_)‑>HourByHourForecast` to disambiguate the third overload.
 
 You can discover the minimal combination of parameter types and return types for each overload from DocC's warnings about ambiguous symbol links.
 

From 840fa930de4ad75fd632e9b3f0833bb871d65306 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Thu, 5 Dec 2024 15:30:43 +0100
Subject: [PATCH 11/12] Add a table of link disambiguation examples

---
 .../linking-to-symbols-and-other-content.md          | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index 77ec5a9d80..4eb6d839e3 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -278,6 +278,18 @@ but using each symbols unique identifier hash for disambiguation:
 - ``forecast(for:at:)-7f3u``
 ```
 
+The table below shows some examples of the types of link disambiguation suffixes that DocC supports:
+
+| Disambiguation type             | Example         | Meaning
+| ------------------------------- | --------------- | ------------
+| Type of symbol                  | `-enum`         | This symbol is an enumeration.
+| Parameter type names            | `-(Int,_,_)`    | This symbol has three parameters and the first parameter is an `Int` value.
+| ^                               | `-()`           | This symbol has no parameters.
+| Return type names               | `->String`      | This symbol returns a `String` value.
+| ^                               | `->(_,_)`       | This symbol returns a tuple with two elements.
+| Parameter and return type names | `-(Bool)->()`   | This symbol has one `Bool` parameter and no return value.
+| Symbol identifier hash          | `-4gcpg`        | The hash of this symbol's unique identifier is "`4gcpg`".
+
 ### Navigate to an Article
 
 To add a link to an article, use the less-than symbol (`<`), the `doc` keyword, 

From 141cef4670a66b27dd6c5fd7886a1ab638476814 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20R=C3=B6nnqvist?= <ronnqvist@apple.com>
Date: Fri, 6 Dec 2024 11:05:15 +0100
Subject: [PATCH 12/12] Apply suggestions from code review

Co-authored-by: Maya Epps <53411851+mayaepps@users.noreply.github.com>
---
 .../linking-to-symbols-and-other-content.md                 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
index 4eb6d839e3..c30e36de92 100644
--- a/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
+++ b/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md
@@ -63,7 +63,7 @@ public struct Sloth {
 ```
 
 > Note:
-If you prefer absolute symbol links you can prefix the symbol path with a leading slash followed by the name of the module that symbol belongs:
+If you prefer absolute symbol links you can prefix the symbol path with a leading slash followed by the name of the module to which that symbol belongs:
 >
 > ```markdown
 > ``/SlothCreator/Sloth``
@@ -243,7 +243,7 @@ The second overload is the only one with where the return value has a `MinuteByM
 so DocC suggests to add `‑>MinuteByMinuteForecast` to disambiguate the second overload.
 
 The third overload has the same parameter types as the second overload and the same return value as the first overload, 
-so DocC neither parameter types or return types alone can uniquely disambiguate this overload.
+so neither parameter types nor return types alone can uniquely disambiguate this overload.
 In this scenario, DocC considers a combination of parameter types and return types to disambiguate the overload.
 The first parameter type is different from the first overload and the return type is different from the second overload.
 Together this information uniquely disambiguates the third overload, 
@@ -268,7 +268,7 @@ If DocC can't disambiguate the symbol link using either a symbol type suffix or
 it will fall back to using a short hash of each symbol's unique identifier to disambiguate the symbol link. 
 You can discover these hashes from DocC's warnings about ambiguous symbol links.
 The following example shows the same topic group with symbol links to the three `forecast(for:at:)` methods as before, 
-but using each symbols unique identifier hash for disambiguation:
+but using each symbol's unique identifier hash for disambiguation:
 
 ```markdown
 ### Requesting weather forecasts