Skip to content

Commit aeb55a3

Browse files
d-ronnqvistmayaepps
d-ronnqvist
and
mayaepps
authored
Document how to disambiguate symbol links using type signature information (#1095)
* Indent table markup for readability * Add more details about how relative symbol links works * Move examples about unambiguous links before "Ambiguous Symbol Links" section. * Reorder list of supported disambiguation symbol types * Add missing supported disambiguation symbol types * Move the symbol type disambiguation example above the hash disambiguation example * Update `Sloth/update(_:)` example to describe type disambiguation rdar://136207820 * Add another more complicated type disambiguation example rdar://136207820 * Minor refinements to the new documentation * Fix 3 incomplete sentences in the new documentation * Add a table of link disambiguation examples * Apply suggestions from code review Co-authored-by: Maya Epps <[email protected]> --------- Co-authored-by: Maya Epps <[email protected]>
1 parent cffe76c commit aeb55a3

File tree

1 file changed

+200
-72
lines changed

1 file changed

+200
-72
lines changed

‎Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md

Lines changed: 200 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -6,74 +6,122 @@ Facilitate navigation between pages using links.
66

77
DocC supports the following link types to enable navigation between pages:
88

9-
| Type | Usage |
10-
| --- | --- |
11-
| Symbol | Links to a symbol's reference page in your documentation. |
12-
| Article | Links to an article or API collection in your documentation catalog. |
13-
| Tutorial | Links to a tutorial in your documentation catalog. |
14-
| Web | Links to an external URL. |
9+
| Type | Usage
10+
| -------- | -----
11+
| Symbol | Links to a symbol's reference page in your documentation.
12+
| Article | Links to an article or API collection in your documentation catalog.
13+
| Tutorial | Links to a tutorial in your documentation catalog.
14+
| Web | Links to an external URL.
1515

1616
### Navigate to a Symbol
1717

18-
To add a link to a symbol, wrap the symbol's name in a set of double backticks
19-
(\`\`).
18+
To add a link to a symbol in your module, wrap the symbol's name in a set of double backticks (\`\`):
2019

2120
```markdown
22-
``SlothCreator``
21+
``Sloth``
2322
```
2423

25-
For nested symbols, include the path to the symbol in the link.
24+
For links to member symbols or nested types, include the path to the symbol in the link:
2625

2726
```markdown
28-
``SlothCreator/Sloth/eat(_:quantity:)``
27+
``Sloth/eat(_:quantity:)``
28+
``Sloth/Food``
2929
```
3030

31-
DocC resolves symbol links relative to the context they appear in. For example,
32-
a symbol link that appears inline in the `Sloth` class, and targets a
33-
symbol in that class, can omit the `SlothCreator/Sloth/` portion of the symbol
34-
path.
31+
DocC resolves symbol links relative to the context that the link appears in.
32+
This allows links in a type's documentation comment to omit the type's name from the symbol path when referring to its members.
33+
For example, in the `Sloth` structure below, the `init(name:color:power:)` symbol link omits the `Sloth/` portion of the symbol path:
3534

36-
In some cases, a symbol's path isn't unique, such as with overloaded methods in
37-
Swift. For example, consider the `Sloth` structure, which has multiple
38-
`update(_:)` methods:
35+
```swift
36+
/// ...
37+
/// You can create a sloth using ``init(name:color:power:)``.
38+
public struct Sloth { // ╰──────────┬──────────╯
39+
/// ... // ╰─────refers-to────╮
40+
public init(name: String, color: Color, power: Power) { // ◁─╯
41+
/* ... */
42+
}
43+
}
44+
```
45+
46+
If DocC can't resolve a link in the current context, it gradually expands the search to the containing scope.
47+
This allows links from one member to another member of the same type to omit the containing type's name from the symbol path.
48+
For example, in the `Sloth` structure below,
49+
the `eat(_:quantity:)` symbol link in the `energyLevel` property's documentation comment omits the `Sloth/` portion of the symbol path:
3950

4051
```swift
41-
/// Updates the sloth's power.
42-
///
43-
/// - Parameter power: The sloth's new power.
44-
mutating public func update(_ power: Power) {
45-
self.power = power
52+
/// ...
53+
public struct Sloth {
54+
/// ...
55+
/// Restore the sloth's energy using ``eat(_:quantity:)``.
56+
public var energyLevel = 10 // ╰───────┬──────╯
57+
// │
58+
/// ... // ╰──────refers-to─────╮
59+
public mutating func eat(_ food: Food, quantity: Int) -> Int { // ◁─╯
60+
/* ... */
61+
}
4662
}
63+
```
4764

48-
/// Updates the sloth's energy level.
49-
///
50-
/// - Parameter energyLevel: The sloth's new energy level.
51-
mutating public func update(_ energyLevel: Int) {
52-
self.energyLevel = energyLevel
65+
> Note:
66+
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:
67+
>
68+
> ```markdown
69+
> ``/SlothCreator/Sloth``
70+
> ``/SlothCreator/Sloth/eat(_:quantity:)``
71+
> ``/SlothCreator/Sloth/Food``
72+
> ```
73+
>
74+
> DocC resolves absolute symbol links from the module's scope instead of the context that the link appears in.
75+
76+
Symbol paths are case-sensitive, meaning that symbols with the same name in different text casing are unambiguous.
77+
For example, consider a `Sloth` structure with both a `color` property and a `Color` enumeration type:
78+
79+
```swift
80+
public struct Sloth {
81+
public var color: Color
82+
83+
public enum Color {
84+
/* ... */
85+
}
5386
}
5487
```
5588
56-
Both methods have an identical symbol path of `SlothCreator/Sloth/update(_:)`.
57-
In this scenario, and to ensure uniqueness, DocC uses the symbol's unique
58-
identifier instead of its name to disambiguate. DocC's warnings about ambiguous
59-
symbol links suggests one disambiguation for each of the symbols that match the
60-
ambiguous symbol path.
89+
A ` ``Sloth/color`` ` symbol link unambiguously refers to the `color` property and a ` ``Sloth/Color`` ` symbol link unambiguously refers to the inner `Color` type.
90+
91+
#### Symbols with Multiple Language Representations
92+
93+
Symbol links to symbols that have representations in more than one programming language can use symbol paths in either source language.
94+
For example, consider a `Sloth` class with `@objc` attributes:
95+
96+
```swift
97+
@objc(TLASloth) public class Sloth: NSObject {
98+
@objc public init(name: String, color: Color, power: Power) {
99+
self.name = name
100+
self.color = color
101+
self.power = power
102+
}
103+
}
104+
```
105+
106+
You can write a symbol link to the Sloth initializer using the symbol path in either source language:
107+
108+
**Swift name**
61109

62110
```markdown
63-
### Updating Sloths
64-
- ``Sloth/update(_:)-4ko57``
65-
- ``Sloth/update(_:)-jixx``
111+
``Sloth/init(name:color:power:)``
112+
```
113+
114+
**Objective-C name**
115+
116+
```markdown
117+
``TLASloth/initWithName:color:power:``
66118
```
67119

68-
In the example above, both symbols are functions, so you need the unique
69-
identifiers to disambiguate the `Sloth/update(_:)` link.
120+
#### Ambiguous Symbol Links
70121

71-
Unique identifiers aren't the only way to disambiguate symbol links. If a symbol
72-
has a different type from the other symbols with the same symbol path, you can
73-
use that symbol's type suffix to disambiguate the link and make the link refer
74-
to that symbol. For example, consider a `Color` structure with `red`, `green`,
75-
and `blue` properties for color components and static properties for a handful
76-
of predefined color values:
122+
In some cases a symbol's path isn't unique.
123+
This makes it ambiguous what specific symbol a symbol link refers to.
124+
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:
77125

78126
```swift
79127
public struct Color {
@@ -87,9 +135,8 @@ extension Color {
87135
}
88136
```
89137

90-
Both the `red` property and the `red` static property have a symbol path of
91-
`Color/red`. Because these are different types of symbols you can disambiguate
92-
`Color/red` with symbol type suffixes instead of the symbols' unique identifiers.
138+
Both the `red` property and the `red` static property have a symbol path of `Color/red`.
139+
Because these are different types of symbols you can disambiguate ` ``Color/red`` ` with a suffix indicating the symbol's type.
93140

94141
The following example shows a symbol link to the `red` property:
95142

@@ -103,65 +150,146 @@ The following example shows a symbol link to the `red` static property:
103150
``Color/red-type.property``
104151
```
105152

106-
DocC supports the following symbol types for use in symbol links:
153+
DocC supports the following symbol types as disambiguation in symbol links:
107154

108155
| Symbol type | Suffix |
109156
|-------------------|-------------------|
110157
| Enumeration | `-enum` |
111158
| Enumeration case | `-enum.case` |
112159
| Protocol | `-protocol` |
113-
| Operator | `-func.op` |
114160
| Typealias | `-typealias` |
115-
| Function | `-func` |
161+
| Associated Type | `-associatedtype` |
116162
| Structure | `-struct` |
117163
| Class | `-class` |
164+
| Function | `-func` |
165+
| Operator | `-func.op` |
166+
| Property | `-property` |
118167
| Type property | `-type.property` |
168+
| Method | `-method` |
119169
| Type method | `-type.method` |
170+
| Subscript | `-subscript` |
120171
| Type subscript | `-type.subscript` |
121-
| Property | `-property` |
122172
| Initializer | `-init` |
123173
| Deinitializer | `-deinit` |
124-
| Method | `-method` |
125-
| Subscript | `-subscript` |
174+
| Global variable | `-var` |
126175
| Instance variable | `-ivar` |
127176
| Macro | `-macro` |
128177
| Module | `-module` |
178+
| Namespace | `-namespace` |
179+
| HTTP Request | `-httpRequest` |
180+
| HTTP Parameter | `-httpParameter` |
181+
| HTTP Response | `-httpResponse` |
182+
| HTTPBody | `-httpBody` |
183+
| Dictionary | `-dictionary` |
184+
| Dictionary Key | `-dictionaryKey` |
129185

130-
Symbol type suffixes can include a source language identifier prefix — for
131-
example, `-swift.enum` instead of `-enum`. However, the language
132-
identifier doesn't disambiguate the link.
186+
You can discover these symbol type suffixes from DocC's warnings about ambiguous symbol links.
187+
DocC suggests one disambiguation for each of the symbols that match the ambiguous symbol path.
133188

134-
Symbol paths are case-sensitive, meaning that symbols with the same name in
135-
different text casing don't need disambiguation.
189+
Symbol type suffixes can include a source language identifier prefix---for example, `-swift.enum` instead of `-enum`.
190+
However, the language identifier doesn't disambiguate the link.
136191

137-
Symbols that have representations in both Swift and Objective-C can use
138-
symbol paths in either source language. For example, consider a `Sloth`
139-
class with `@objc` attributes:
192+
193+
In the example above, both symbols that match the ambiguous symbol path were different types of symbol.
194+
If the symbols that match the ambiguous symbol path have are the same type of symbol,
195+
such as with overloaded methods in Swift, a symbol type suffix won't disambiguate the link.
196+
In this scenario, DocC uses information from the symbols' type signatures to disambiguate.
197+
For example, consider the `Sloth` structure---from the SlothCreator example---which has two different `update(_:)` methods:
140198

141199
```swift
142-
@objc(TLASloth) public class Sloth: NSObject {
143-
@objc public init(name: String, color: Color, power: Power) {
144-
self.name = name
145-
self.color = color
146-
self.power = power
147-
}
200+
/// Updates the sloth's power.
201+
///
202+
/// - Parameter power: The sloth's new power.
203+
mutating public func update(_ power: Power) {
204+
self.power = power
205+
}
206+
207+
/// Updates the sloth's energy level.
208+
///
209+
/// - Parameter energyLevel: The sloth's new energy level.
210+
mutating public func update(_ energyLevel: Int) {
211+
self.energyLevel = energyLevel
148212
}
149213
```
150214

151-
You can write a symbol link to the Sloth initializer using the symbol path in either source language.
215+
Both methods have an identical symbol path of `SlothCreator/Sloth/update(_:)`.
216+
In this example there's only one parameter and its type is `Power` for the first overload and `Int` for the second overload.
217+
DocC uses this parameter type information to suggest adding `(Power)` and `(Int)` to disambiguate each respective overload.
152218

153-
**Swift name**
219+
The following example shows a topic group with disambiguated symbol links to both `Sloth/update(_:)` methods:
154220

155221
```markdown
156-
``Sloth/init(name:color:power:)``
222+
### Updating Sloths
223+
224+
- ``Sloth/update(_:)-(Power)``
225+
- ``Sloth/update(_:)-(Int)``
157226
```
158227

159-
**Objective-C name**
228+
If there are more overloads with more parameters and return values,
229+
DocC may suggest a combination of parameter types and return value types to uniquely disambiguate each overload.
230+
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:
231+
232+
```swift
233+
public func forecast(for days: DateInterval, at location: Location) -> HourByHourForecast { /* ... */ }
234+
public func forecast(for day: Date, at location: Location) -> MinuteByMinuteForecast { /* ... */ }
235+
public func forecast(for day: Date, at location: Location) -> HourByHourForecast { /* ... */ }
236+
```
237+
238+
The first overload is the only one with where the first parameter has a `DateInterval` type.
239+
The second parameter type isn't necessary to disambiguate the overload, and is the same in all three overloads,
240+
so DocC suggests to add `(DateInterval,_)` to disambiguate the first overload.
241+
242+
The second overload is the only one with where the return value has a `MinuteByMinuteForecast` type,
243+
so DocC suggests to add `‑>MinuteByMinuteForecast` to disambiguate the second overload.
244+
245+
The third overload has the same parameter types as the second overload and the same return value as the first overload,
246+
so neither parameter types nor return types alone can uniquely disambiguate this overload.
247+
In this scenario, DocC considers a combination of parameter types and return types to disambiguate the overload.
248+
The first parameter type is different from the first overload and the return type is different from the second overload.
249+
Together this information uniquely disambiguates the third overload,
250+
so DocC suggests to add `(Date,_)‑>HourByHourForecast` to disambiguate the third overload.
251+
252+
You can discover the minimal combination of parameter types and return types for each overload from DocC's warnings about ambiguous symbol links.
253+
254+
The following example shows a topic group with disambiguated symbol links to the three `forecast(for:at:)` methods from before:
160255

161256
```markdown
162-
``TLASloth/initWithName:color:power:``
257+
### Requesting weather forecasts
258+
259+
- ``forecast(for:at:)-(DateInterval,_)``
260+
- ``forecast(for:at:)->MinuteByMinuteForecast``
261+
- ``forecast(for:at:)->(Date,_)->HourByHourForecast``
262+
```
263+
264+
> Earlier Versions:
265+
> Before Swift-DocC 6.1, disambiguation using parameter types or return types isn't supported.
266+
267+
If DocC can't disambiguate the symbol link using either a symbol type suffix or a combination parameter type names and return type names,
268+
it will fall back to using a short hash of each symbol's unique identifier to disambiguate the symbol link.
269+
You can discover these hashes from DocC's warnings about ambiguous symbol links.
270+
The following example shows the same topic group with symbol links to the three `forecast(for:at:)` methods as before,
271+
but using each symbol's unique identifier hash for disambiguation:
272+
273+
```markdown
274+
### Requesting weather forecasts
275+
276+
- ``forecast(for:at:)-3brnk``
277+
- ``forecast(for:at:)-4gcpg``
278+
- ``forecast(for:at:)-7f3u``
163279
```
164280

281+
The table below shows some examples of the types of link disambiguation suffixes that DocC supports:
282+
283+
| Disambiguation type | Example | Meaning
284+
| ------------------------------- | --------------- | ------------
285+
| Type of symbol | `-enum` | This symbol is an enumeration.
286+
| Parameter type names | `-(Int,_,_)` | This symbol has three parameters and the first parameter is an `Int` value.
287+
| ^ | `-()` | This symbol has no parameters.
288+
| Return type names | `->String` | This symbol returns a `String` value.
289+
| ^ | `->(_,_)` | This symbol returns a tuple with two elements.
290+
| Parameter and return type names | `-(Bool)->()` | This symbol has one `Bool` parameter and no return value.
291+
| Symbol identifier hash | `-4gcpg` | The hash of this symbol's unique identifier is "`4gcpg`".
292+
165293
### Navigate to an Article
166294

167295
To add a link to an article, use the less-than symbol (`<`), the `doc` keyword,

0 commit comments

Comments
 (0)