Skip to content

Commit cc7c052

Browse files
stephencelisstephencelis
committed
Update DocC
1 parent ae8aa94 commit cc7c052

19 files changed

+106
-103
lines changed

‎.spi.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
version: 1
22
builder:
33
configs:
4-
- documentation_targets: [CasePaths]
4+
- documentation_targets: [CasePathsCore, CasePaths]

‎Sources/CasePaths/Documentation.docc/AnyCasePathDeprecations.md

Lines changed: 0 additions & 38 deletions
This file was deleted.

‎Sources/CasePaths/Documentation.docc/CasePathableMacro.md

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
# ``CasePaths/CasePathable()``
22

3-
## Topics
3+
## Further reading
44

5-
### CasePathable conformance
6-
7-
- ``CasePathable``
5+
See the [`CasePathsCore`](../casepathscore) module for the `CasePathable` protocol and other core
6+
library types.

‎Sources/CasePaths/Documentation.docc/CasePaths.md

Lines changed: 4 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,31 +4,17 @@ Case paths bring the power and ergonomics of key paths to enums.
44

55
## Overview
66

7-
<!-- TODO: Copy over README -->
7+
This module exports the core functionality of the Case Paths library, as well as the `@CasePathable`
8+
macro.
89

9-
## Topics
10-
11-
### Case paths
10+
To read the core documentation, see the [`CasePathsCore`](../casepathscore) module.
1211

13-
- ``CaseKeyPath``
12+
## Topics
1413

1514
### Creating case paths
1615

1716
- ``CasePathable()``
1817

19-
### Swift support
20-
21-
- ``Swift/Optional``
22-
- ``Swift/Result``
23-
24-
### XCTest support
25-
26-
- ``XCTModify(_:case:_:_:file:line:)-94qma``
27-
28-
### Guides
29-
30-
- <doc:Swift59>
31-
3218
### Deprecated interfaces
3319

3420
- <doc:Deprecations>

‎Sources/CasePaths/Documentation.docc/Deprecations.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,17 @@ Avoid using deprecated APIs in your app. See the replacement that you should use
1414
- ``extract(case:from:)-ylkc``
1515
- ``extract(_:)-34fjh``
1616
- ``extract(_:)-3twft``
17+
18+
### Creating paths
19+
20+
- ``CasePathsCore/AnyCasePath``
21+
22+
### Type aliases
23+
24+
- ``CasePath``
25+
26+
### Test helpers
27+
28+
- ``XCTModify(_:case:_:_:file:line:)-14526``
29+
- ``XCTModify(_:case:_:_:file:line:)-1pef3``
30+
- ``XCTModify(_:_:_:file:line:)``

‎Sources/CasePaths/Documentation.docc/XCTModify.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# ``CasePaths/XCTModify(_:case:_:_:file:line:)-94qma``
1+
# ``CasePaths/XCTModify(_:case:_:_:file:line:)-14526``
22

33
## Topics
44

‎Sources/CasePaths/Documentation.docc/XCTModifyDeprecations.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Avoid using deprecated APIs in your app. See the replacement that you should use
1010

1111
### XCTModify
1212

13-
- ``XCTModify(_:case:_:_:file:line:)-1lm9s``
13+
- ``XCTModify(_:case:_:_:file:line:)-1pef3``
1414

1515
### XCTUnwrap
1616

‎Sources/CasePaths/EnumReflection.swift

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@ extension AnyCasePath {
77
/// given an enum embed function.
88
///
99
/// > Important: This operation is provided for backwards compatibility. Avoid introducing it to
10-
/// > your code and instead favor using types that conform to ``CasePathable`` and
11-
/// > ``CaseKeyPath``.
10+
/// > your code and instead favor using types that employ the ``CasePathable()`` macro.
1211
///
1312
/// - Parameter embed: An embed function.
1413
@available(iOS, deprecated: 9999, message: "Use a 'CasePathable' case key path, instead")
@@ -34,8 +33,7 @@ extension AnyCasePath {
3433
/// Returns a void case path for a case with no associated value.
3534
///
3635
/// > Important: This operation is provided for backwards compatibility. Avoid introducing it to
37-
/// > your code and instead favor using types that conform to ``CasePathable`` and
38-
/// > ``CaseKeyPath``.
36+
/// > your code and instead favor using types that employ the ``CasePathable()`` macro.
3937
@available(iOS, deprecated: 9999, message: "Use a 'CasePathable' case key path, instead")
4038
@available(macOS, deprecated: 9999, message: "Use a 'CasePathable' case key path, instead")
4139
@available(tvOS, deprecated: 9999, message: "Use a 'CasePathable' case key path, instead")

‎Sources/CasePaths/Internal/Deprecations.swift

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,12 +66,14 @@ extension AnyCasePath where Root: _OptionalProtocol, Value == Root.Wrapped {
6666
}
6767
}
6868

69+
@_documentation(visibility: private)
6970
public protocol _OptionalProtocol {
7071
associatedtype Wrapped
7172
var optional: Wrapped? { get }
7273
init(_ some: Wrapped)
7374
}
7475

76+
@_documentation(visibility: private)
7577
extension Optional: _OptionalProtocol {
7678
public var optional: Wrapped? { self }
7779
}
@@ -295,8 +297,8 @@ public func XCTModify<Enum, Case>(
295297
/// A type-erased case path that supports embedding a value in a root and attempting to extract a
296298
/// root's embedded value.
297299
///
298-
/// This type has been renamed to ``AnyCasePath`` and is primarily employed by the
299-
/// ``CasePathable()`` macro to derive ``CaseKeyPath``s from an enum's cases.
300+
/// This type has been renamed to `AnyCasePath` and is primarily employed by the ``CasePathable()``
301+
/// macro to derive `CaseKeyPath`s from an enum's cases.
300302
@available(*, deprecated, renamed: "AnyCasePath")
301303
public typealias CasePath = AnyCasePath
302304

‎Sources/CasePaths/Macros.swift

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/// Defines and implements conformance of the CasePathable protocol.
22
///
3-
/// This macro conforms the type to the ``CasePathable`` protocol, and adds ``CaseKeyPath``
4-
/// support for all its cases.
3+
/// This macro conforms the type to the `CasePathable` protocol, and adds `CaseKeyPath` support for
4+
/// all its cases.
55
///
66
/// For example, the following code applies the `CasePathable` macro to the type `UserAction`:
77
///

‎Sources/CasePathsCore/CasePathIterable.swift

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
/// A type that provides a collection of all of its case paths.
22
///
3-
/// The ``CasePathable()`` macro automatically generates a conformance to this protocol.
3+
/// The `@CasePathable` macro automatically generates a conformance to this protocol.
44
///
55
/// You can iterate over ``CasePathable/allCasePaths`` to get access to each individual case path:
66
///

‎Sources/CasePathsCore/CasePathReflectable.swift

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
/// A type that can reflect a case path from a given case.
22
///
3-
/// The ``CasePathable()`` macro automatically generates a conformance to this protocol on the
4-
/// enum's ``CasePathable/AllCasePaths`` type.
3+
/// The `@CasePathable` macro automatically generates a conformance to this protocol on the enum's
4+
/// ``CasePathable/AllCasePaths`` type.
55
///
6-
/// You can look up an enum's case path by passing it to ``subscript(root:)``:
6+
/// You can look up an enum's case path by passing it to ``CasePathReflectable/subscript(_:)``:
77
///
88
/// ```swift
99
/// @CasePathable

‎Sources/CasePathsCore/CasePathable.swift

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,7 @@ import IssueReporting
22

33
/// A type that provides a collection of all of its case paths.
44
///
5-
/// Use the ``CasePathable()`` macro to automatically add case paths, and this conformance, to an
6-
/// enum.
5+
/// Use the `@CasePathable` macro to automatically add case paths, and this conformance, to an enum.
76
///
87
/// It is also possible, though less common, to manually conform a type to `CasePathable`. For
98
/// example, the `Result` type is extended to be case-pathable with the following extension:
@@ -105,12 +104,12 @@ extension Case: _AnyCase {
105104

106105
/// A key path to the associated value of an enum case.
107106
///
108-
/// The most common way to make an instance of this type is by applying the ``CasePathable()`` macro
107+
/// The most common way to make an instance of this type is by applying the `@CasePathable` macro
109108
/// to an enum and using a key path expression like `\SomeEnum.Cases.someCase`, or simply
110109
/// `\.someCase` where the type can be inferred.
111110
///
112111
/// To extract an associated value from an enum using a case key path, pass the key path to the
113-
/// ``CasePathable/subscript(case:)-6cdhl``. For example:
112+
/// ``CasePathable/subscript(case:)-3yqx3``. For example:
114113
///
115114
/// ```swift
116115
/// @CasePathable
@@ -129,7 +128,7 @@ extension Case: _AnyCase {
129128
/// // anotherValue is nil
130129
/// ```
131130
///
132-
/// To replace an associated value, assign it through ``CasePathable/subscript(case:)-8yr2s``. If
131+
/// To replace an associated value, assign it through ``CasePathable/subscript(case:)-2t4f8``. If
133132
/// the given path does not match the given enum case, the replacement will fail. For
134133
/// example:
135134
///
@@ -321,7 +320,7 @@ extension CasePathable {
321320
/// e[case: \.anotherCase] // nil
322321
/// ```
323322
///
324-
/// See ``CasePathable/subscript(case:)-8yr2s`` for replacing an associated value in a root
323+
/// See ``CasePathable/subscript(case:)-2t4f8`` for replacing an associated value in a root
325324
/// enum, and see ``Swift/KeyPath/callAsFunction(_:)`` for embedding an associated value in a
326325
/// brand new root enum.
327326
public subscript<Value>(case keyPath: CaseKeyPath<Self, Value>) -> Value? {
@@ -354,7 +353,7 @@ extension CasePathable {
354353
/// // e is still SomeEnum.someCase(24)
355354
/// ```
356355
///
357-
/// See ``CasePathable/subscript(case:)-6cdhl`` for extracting an associated value from a root
356+
/// See ``CasePathable/subscript(case:)-3yqx3`` for extracting an associated value from a root
358357
/// enum, and see ``Swift/KeyPath/callAsFunction(_:)`` for embedding an associated value in a
359358
/// brand new root enum.
360359
@_disfavoredOverload

‎Sources/CasePathsCore/Documentation.docc/CasePathsCore.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# ``CasePathsCore``
2+
3+
Case paths bring the power and ergonomics of key paths to enums.
4+
5+
## Overview
6+
7+
This module contains the core functionality of the Case Paths library, minus the `@CasePathable`
8+
macro, and is automatically imported when you `import CasePaths`
9+
10+
See the [`CasePaths`](../casepaths) module for information about the `@CasePathable` macro and
11+
other non-core functionality.
12+
13+
## Topics
14+
15+
### Creating case paths
16+
17+
- ``CasePathable``
18+
- ``CaseKeyPath``
19+
20+
### Swift support
21+
22+
- ``Swift/Optional``
23+
- ``Swift/Result``
24+
- ``Swift/Never``
25+
26+
### Migration guides
27+
28+
- <doc:MigrationGuides>

‎Sources/CasePaths/Documentation.docc/AnyCasePath.md renamed to ‎Sources/CasePathsCore/Documentation.docc/Extensions/AnyCasePath.md

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
# ``CasePaths/AnyCasePath``
1+
# ``CasePathsCore/AnyCasePath``
22

33
## Topics
44

55
### Creating paths
66

77
- ``init(embed:extract:)``
8-
- ``init(_:)-65qkv``
8+
- ``init(_:)``
99
- ``init()``
1010

1111
### Extracting and embedding values
@@ -16,7 +16,3 @@
1616
### Appending paths
1717

1818
- ``subscript(dynamicMember:)``
19-
20-
### Deprecated interfaces
21-
22-
- <doc:AnyCasePathDeprecations>

‎Sources/CasePaths/Documentation.docc/CaseKeyPath.md renamed to ‎Sources/CasePathsCore/Documentation.docc/Extensions/CaseKeyPath.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,4 @@
1414
### Partial case paths
1515

1616
- ``PartialCaseKeyPath``
17-
- ``CasePathable/subscript(case:)-8av06``
17+
- ``CasePathable/subscript(case:)-73fim``

‎Sources/CasePaths/Documentation.docc/CasePathable.md renamed to ‎Sources/CasePathsCore/Documentation.docc/Extensions/CasePathable.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# ``CasePaths/CasePathable``
1+
# ``CasePathsCore/CasePathable``
22

33
## Topics
44

@@ -8,15 +8,15 @@
88

99
### Extracting, replacing, and modifying values
1010

11-
- ``subscript(case:)-6cdhl``
12-
- ``subscript(case:)-8yr2s``
11+
- ``subscript(case:)-3yqx3``
12+
- ``subscript(case:)-2t4f8``
1313
- ``modify(_:yield:fileID:filePath:line:column:)``
1414

1515
### Case properties
1616

1717
- ``is(_:)``
18-
- ``subscript(dynamicMember:)-7ik0u``
19-
- ``subscript(dynamicMember:)-7sz4x``
18+
- ``subscript(dynamicMember:)-emck``
19+
- ``subscript(dynamicMember:)-dm5y``
2020

2121
### Iteration and reflection
2222

‎Sources/CasePathsCore/Documentation.docc/MigrationGuides.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Migration guides
2+
3+
Learn how to upgrade your application to the newest version of Case Paths.
4+
5+
## Overview
6+
7+
Case Paths is under constant development, and we are always looking for ways to simplify the
8+
library, and make it more powerful. As such, we often need to deprecate certain APIs in favor of
9+
newer ones. We recommend people update their code as quickly as possible to the newest APIs, and
10+
these guides contain tips to do so.
11+
12+
> Important: Before following any particular migration guide be sure you have followed all the
13+
> preceding migration guides.
14+
15+
## Topics
16+
17+
- <doc:MigratingTo1.1>

0 commit comments

Comments
 (0)