Skip to content

Commit 77d38c0

Browse files
orchetectorchetect
committed
Updated docs
1 parent 3cb4cb0 commit 77d38c0

9 files changed

Lines changed: 90 additions & 55 deletions

File tree

‎Sources/TimecodeKit/Documentation.docc/Documentation.md‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ``TimecodeKit``
22

3-
Value types, AV methods and UI components for representing and working with SMPTE/EBU timecode.
3+
Umbrella module that imports the entire TimecodeKit library. Contains a Getting Started guide.
44

55
![TimecodeKit](timecodekit-banner.png)
66

@@ -17,13 +17,7 @@ For UI components, see <doc://TimecodeKit/TimecodeKitUI> documentation.
1717
- <doc:Getting-Started>
1818
- <doc:TimecodeKit-2-Migration-Guide>
1919

20-
### Formats Addendum
20+
### Transport Formats
2121

2222
- <doc:LTC-Linear-Timecode>
2323
- <doc:MTC-MIDI-Timecode>
24-
25-
### Modules
26-
27-
- <doc://TimecodeKit/TimecodeKitCore>
28-
- <doc://TimecodeKit/TimecodeKitAV>
29-
- <doc://TimecodeKit/TimecodeKitUI>

‎Sources/TimecodeKit/Documentation.docc/Getting-Started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,6 @@ The documentation page for <doc://TimecodeKit/TimecodeKitCore/Timecode-swift.str
2626

2727
Example projects are located in the Examples folder to demonstrate usage of the library.
2828

29-
The topics list in the sidebar give overviews of specific areas of concern.
29+
The topics list in the sidebar give overviews of specific areas of concern, broken down by module.
3030

3131
If upgrading from TimecodeKit 1.x, see <doc:TimecodeKit-2-Migration-Guide>.

‎Sources/TimecodeKitCore/Documentation.docc/Timecode-Conversions.md‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@ Converting various time values to/from timecode.
66

77
```swift
88
// convert between frame rates
9-
let tc = try "01:00:00;00"
10-
.timecode(at: .fps29_97d)
9+
let tc = try Timecode(.string("01:00:00;00"), at: .fps29_97d)
1110
.converted(to: .fps29_97) // == 00:59:56:12
1211
```
1312

@@ -51,8 +50,7 @@ See <doc:Timecode-String> for more details.
5150

5251
```swift
5352
// timecode → elapsed real-world wall time in seconds
54-
try "01:00:00:00"
55-
.timecode(at: .fps23_976)
53+
try Timecode(.string("01:00:00:00"), at: .fps23_976)
5654
.realTimeValue // == 3603.6 as TimeInterval (Double)
5755
```
5856

@@ -65,8 +63,7 @@ try Timecode(.realTime(seconds: 3603.6), at: .fps23_976)
6563

6664
```swift
6765
// timecode → elapsed audio samples
68-
try "01:00:00:00"
69-
.timecode(at: .fps24)
66+
try Timecode(.string("01:00:00:00"), at: .fps24)
7067
.samplesValue(sampleRate: 48000) // == 172800000
7168
```
7269

@@ -83,8 +80,7 @@ See <doc:Rational-Numbers-and-CMTime> for more details.
8380

8481
```swift
8582
// timecode → feet+frames
86-
try "01:00:00:00"
87-
.timecode(at: .fps23_976)
83+
try Timecode(.string("01:00:00:00"), at: .fps23_976)
8884
.feetAndFramesValue // 5400+00
8985
```
9086

‎Sources/TimecodeKitCore/Documentation.docc/Timecode-Encoding.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,12 +38,12 @@ This means that the end-user is able to:
3838

3939
```swift
4040
struct TimecodeListView: View {
41-
@State var timecodes: [Timecode]
41+
@State var model: [Timecode]
4242
@State var selection: Timecode
4343

4444
var body: some View {
4545
List(selection: $selection) {
46-
ForEach(timecodes) { item in
46+
ForEach(model) { item in
4747
Text(item.stringValue()).tag(item)
4848
}
4949
}
@@ -72,7 +72,7 @@ struct TimecodeListView: View {
7272

7373
// Timecode's default Identifiable implementation uses self
7474
// which means we cannot have two identical timecodes in a SwiftUI array
75-
if !timecodes.contains(timecode) { timecodes.append(timecode) }
75+
if !model.contains(timecode) { model.append(timecode) }
7676
}
7777
}
7878
```
@@ -85,12 +85,12 @@ The following example demonstrates a timecode list that supports copy and paste
8585

8686
```swift
8787
struct TimecodeListView: View {
88-
@State var timecodes: [Timecode]
88+
@State var model: [Timecode]
8989
@State var selection: Timecode
9090

9191
var body: some View {
9292
List(selection: $selection) {
93-
ForEach(timecodes) { item in
93+
ForEach(model) { item in
9494
Text(item.stringValue()).tag(item)
9595
}
9696
.dropDestination(for: Timecode.self) { items, location in
@@ -108,7 +108,7 @@ struct TimecodeListView: View {
108108
// Timecode's default Identifiable implementation uses self
109109
// which means we cannot have two identical timecodes in a SwiftUI array
110110
items.forEach {
111-
if !timecodes.contains($0) { timecodes.append($0) }
111+
if !model.contains($0) { model.append($0) }
112112
}
113113
}
114114
}

‎Sources/TimecodeKitCore/Timecode/Source/Timecode String.swift‎

Lines changed: 61 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,55 @@ extension String: _FormattedTimecodeSource {
3737

3838
extension FormattedTimecodeSourceValue {
3939
/// Timecode string.
40+
///
41+
/// Valid formats for 24-hour:
42+
///
43+
/// ```
44+
/// "00:00:00:00" "00:00:00;00"
45+
/// "00:00:00:00.00" "00:00:00;00.00"
46+
/// "00;00;00;00" "00;00;00;00"
47+
/// "00;00;00;00.00" "00;00;00;00.00"
48+
/// ```
49+
///
50+
/// Valid formats for 100-day: All of the above, as well as:
51+
///
52+
/// ```
53+
/// "0 00:00:00:00" "0 00:00:00;00"
54+
/// "0:00:00:00:00" "0:00:00:00;00"
55+
/// "0 00:00:00:00.00" "0 00:00:00;00.00"
56+
/// "0:00:00:00:00.00" "0:00:00:00;00.00"
57+
/// "0 00;00;00;00" "0 00;00;00;00"
58+
/// "0;00;00;00;00" "0;00;00;00;00"
59+
/// "0 00;00;00;00.00" "0 00;00;00;00.00"
60+
/// "0;00;00;00;00.00" "0;00;00;00;00.00"
61+
/// ```
4062
public static func string(_ timecodeString: String) -> Self {
4163
.init(value: timecodeString)
4264
}
4365

4466
/// Timecode string.
67+
///
68+
/// Valid formats for 24-hour:
69+
///
70+
/// ```
71+
/// "00:00:00:00" "00:00:00;00"
72+
/// "00:00:00:00.00" "00:00:00;00.00"
73+
/// "00;00;00;00" "00;00;00;00"
74+
/// "00;00;00;00.00" "00;00;00;00.00"
75+
/// ```
76+
///
77+
/// Valid formats for 100-day: All of the above, as well as:
78+
///
79+
/// ```
80+
/// "0 00:00:00:00" "0 00:00:00;00"
81+
/// "0:00:00:00:00" "0:00:00:00;00"
82+
/// "0 00:00:00:00.00" "0 00:00:00;00.00"
83+
/// "0:00:00:00:00.00" "0:00:00:00;00.00"
84+
/// "0 00;00;00;00" "0 00;00;00;00"
85+
/// "0;00;00;00;00" "0;00;00;00;00"
86+
/// "0 00;00;00;00.00" "0 00;00;00;00.00"
87+
/// "0;00;00;00;00.00" "0;00;00;00;00.00"
88+
/// ```
4589
@_disfavoredOverload
4690
public static func string(_ timecodeString: some StringProtocol) -> Self {
4791
.init(value: String(timecodeString))
@@ -53,20 +97,7 @@ extension FormattedTimecodeSourceValue {
5397
extension Timecode {
5498
// MARK: stringValue
5599

56-
/// Timecode string representation.
57-
///
58-
/// Valid formats for 24-hour:
59-
///
60-
/// "00:00:00:00" "00:00:00;00"
61-
/// "0:00:00:00" "0:00:00;00"
62-
/// "00000000"
63-
///
64-
/// Valid formats for 100-day: All of the above, as well as:
65-
///
66-
/// "0 00:00:00:00" "0 00:00:00;00"
67-
/// "0:00:00:00:00" "0:00:00:00;00"
68-
///
69-
/// (Validation is based on the frame rate and `upperLimit` property.)
100+
/// Returns the timecode's string representation.
70101
public func stringValue(
71102
format: StringFormat = .default()
72103
) -> String {
@@ -170,21 +201,25 @@ extension Timecode {
170201
///
171202
/// Valid formats for 24-hour:
172203
///
173-
/// "00:00:00:00" "00:00:00;00"
174-
/// "00:00:00:00.00" "00:00:00;00.00"
175-
/// "00;00;00;00" "00;00;00;00"
176-
/// "00;00;00;00.00" "00;00;00;00.00"
204+
/// ```
205+
/// "00:00:00:00" "00:00:00;00"
206+
/// "00:00:00:00.00" "00:00:00;00.00"
207+
/// "00;00;00;00" "00;00;00;00"
208+
/// "00;00;00;00.00" "00;00;00;00.00"
209+
/// ```
177210
///
178211
/// Valid formats for 100-day: All of the above, as well as:
179212
///
180-
/// "0 00:00:00:00" "0 00:00:00;00"
181-
/// "0:00:00:00:00" "0:00:00:00;00"
182-
/// "0 00:00:00:00.00" "0 00:00:00;00.00"
183-
/// "0:00:00:00:00.00" "0:00:00:00;00.00"
184-
/// "0 00;00;00;00" "0 00;00;00;00"
185-
/// "0;00;00;00;00" "0;00;00;00;00"
186-
/// "0 00;00;00;00.00" "0 00;00;00;00.00"
187-
/// "0;00;00;00;00.00" "0;00;00;00;00.00"
213+
/// ```
214+
/// "0 00:00:00:00" "0 00:00:00;00"
215+
/// "0:00:00:00:00" "0:00:00:00;00"
216+
/// "0 00:00:00:00.00" "0 00:00:00;00.00"
217+
/// "0:00:00:00:00.00" "0:00:00:00;00.00"
218+
/// "0 00;00;00;00" "0 00;00;00;00"
219+
/// "0;00;00;00;00" "0;00;00;00;00"
220+
/// "0 00;00;00;00.00" "0 00;00;00;00.00"
221+
/// "0;00;00;00;00.00" "0;00;00;00;00.00"
222+
/// ```
188223
///
189224
/// - Throws: ``StringParseError``
190225
package static func decode(timecode string: some StringProtocol) throws -> Components {

‎Sources/TimecodeKitCore/Timecode/Timecode Conversion.swift‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,9 @@ extension Timecode {
1515
/// - newFrameRate: New frame rate.
1616
/// If the new rate is identical to the current rate, the timecode will be returned unchanged.
1717
///
18-
/// - newSubFramesBase: New sub-frames base (optional).
18+
/// - newSubFramesBase: New subframes base (optional).
1919
///
20-
/// If not specified, the current sub-frames base will be preserved.
20+
/// If not specified, the current subframes base will be preserved.
2121
///
2222
/// - preservingValues: Preserve literal timecode component values. (Default: `false`)
2323
///
@@ -28,7 +28,7 @@ extension Timecode {
2828
///
2929
/// - Throws: ``ValidationError``
3030
///
31-
/// - Returns: A new `Timecode` instance converted to the new frame rate and sub-frames base.
31+
/// - Returns: A new `Timecode` instance converted to the new frame rate and subframes base.
3232
public func converted(
3333
to newFrameRate: TimecodeFrameRate,
3434
base newSubFramesBase: Timecode.SubFramesBase? = nil,

‎Sources/TimecodeKitUI/Attributed String/NSAttributedString.swift‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ extension NSAttributedString {
1717
/// For example, to colorize invalid timecode components values using red:
1818
///
1919
/// ```swift
20+
/// let timecode = try Timecode(.string("01:20:10:15"), at: .fps24)
21+
///
2022
/// // macOS (AppKit)
2123
/// NSAttributedString(
2224
/// timecode,
@@ -59,6 +61,8 @@ extension Timecode {
5961
/// For example, to colorize invalid timecode components values using red:
6062
///
6163
/// ```swift
64+
/// let timecode = try Timecode(.string("01:20:10:15"), at: .fps24)
65+
///
6266
/// // macOS (AppKit)
6367
/// timecode.nsAttributedString(
6468
/// invalidAttributes: [.foregroundColor: NSColor.red]

‎Sources/TimecodeKitUI/Documentation.docc/Documentation.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@ UI controls and tools for formatting and displaying timecode, including user-edi
3737
### AttributedString
3838

3939
- ``Foundation/AttributedString/init(_:format:separatorStyle:validationStyle:)``
40+
41+
### NSAttributedString
42+
43+
- ``Foundation/NSAttributedString/init(_:format:defaultAttributes:invalidAttributes:)``
4044
- ``TimecodeKitCore/Timecode/nsAttributedString(format:defaultAttributes:invalidAttributes:)``
4145

4246
### Formatter

‎Sources/TimecodeKitUI/SwiftUI/TimecodeField/TimecodeField.swift‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import TimecodeKitCore
1414
///
1515
/// ## Initializers
1616
///
17-
/// The view may be initialized to a `Timecode` instance directly. In this case, it is required to store the
17+
/// The view may be initialized with a `Timecode` binding. In this case, it is required to store the
1818
/// `Timecode` instance in the view using the custom ``TimecodeState`` wrapper in place of the typical SwiftUI
1919
/// `@State` wrapper.
2020
///
@@ -67,6 +67,8 @@ import TimecodeKitCore
6767
/// .timecodeFieldValidationPolicy(.enforceValid, animation: true)
6868
/// ```
6969
///
70+
/// For a demonstration, see the **Timecode UI** example project in this repo.
71+
///
7072
/// ## Focus
7173
///
7274
/// Each timecode component individually receives focus one at a time.
@@ -86,10 +88,10 @@ import TimecodeKitCore
8688
/// | --- | --- |
8789
/// | Numeric digit keys | Enters digits for the currently focused timecode component. |
8890
/// | `Return` or `Escape` | Can be used to remove focus from the field. |
89-
/// | `Backspace` | Resets the timecode component to zero if it has freshly received focus. Once the user begins to enter digits into the component, the Backspace key will function as single digit delete akin to a text-entry field.
91+
/// | `Backspace` | Resets the timecode component to zero if it has freshly received focus. Once the user begins to enter digits into the component, the Backspace key will function as single digit delete akin to a typical text-entry field.
9092
/// | `Delete` (`Del` key, or `forwardDelete`) | Resets the component to zero. |
9193
///
92-
/// For keys that navigate timecode component focus, see the Focus section above.
94+
/// For keys that navigate timecode component focus, see the <doc:#Focus> section above.
9395
@available(macOS 14.0, iOS 17.0, tvOS 17.0, watchOS 10.0, *)
9496
public struct TimecodeField: View {
9597
// MARK: - Standard Environment

0 commit comments

Comments
 (0)