Update documentation

Author: jordanbaird

Sources/SwiftKeys/Documentation.docc/Articles/GettingStarted.md

@@ -8,7 +8,7 @@ There are two top-level types in this package: ``KeyCommand`` and ``KeyRecorder`
 
 #### KeyCommand
 
-``KeyCommand`` is quite powerful, yet simple to understand. To create one, all you need is a name, which will be used to store the command in `UserDefaults`.
+To create a ``KeyCommand``, all you need is a name, which will be used to store the command in `UserDefaults`.
 
 ```swift
 let command = KeyCommand(name: "OpenPreferences")
@@ -79,7 +79,7 @@ In addition to operating on the key command itself, you can perform similar chan
 
 ``KeyRecorder`` is a subclass of `NSControl` that enables you to record new keys and modifiers for a key command. Passing a command into ``KeyRecorder/init(keyCommand:)`` creates a key recorder whose state is bound to that command. You can also create a key recorder using ``KeyRecorder/init(name:)``, a convenience initializer which automatically creates a key command based on the name you provide.
 
-![A window containing a KeyRecorder.](recorder-window.png)
+![A window containing a KeyRecorder.](recorder-window)
 
 Using a key recorder is extremely simple. Clicking inside puts it into "recording" mode, where it awaits a key-down message. As soon as a key combination is pressed, the recorder updates its key command and enters "idle" mode. In idle mode, a "clear" button appears, which resets the key command to an empty state.
 

Sources/SwiftKeys/Documentation.docc/SwiftKeys.md

@@ -6,42 +6,99 @@ A straightforward global key command API for macOS.
 
 `SwiftKeys` allows you to create, observe, and record global hotkeys.
 
-Start by creating an instance of ``KeyCommand``. Then, use it to initialize a ``KeyRecorder`` instance. The key recorder's state is bound to the key command, so when it records a new key combination, the command will be updated. You can also observe the command and perform actions on both key-down and key-up.
+### Creating and Observing
+
+Start by creating an instance of ``KeyCommand``. Observe it, and perform actions on ``KeyCommand/EventType/keyDown``, ``KeyCommand/EventType/keyUp``, and ``KeyCommand/EventType/doubleTap(_:)``:
 
 ```swift
-let command = KeyCommand(name: "SomeCommand")
-let recorder = KeyRecorder(keyCommand: command)
+let command = KeyCommand(name: "ToggleMainWindow")
 
 command.observe(.keyDown) {
-    print("DOWN")
+    myCustomKeyDownAction()
 }
+
 command.observe(.keyUp) {
-    print("UP")
+    myCustomKeyUpAction()
+}
+
+command.observe(.doubleTap(0.2)) {
+    myCustomDoubleTapAction()
 }
 ```
 
-For improved type safety, you can create hard-coded key command names that can be referenced across your app.
+> ``KeyCommand/EventType/doubleTap(_:)`` allows you to specify a maximum time interval that the two key presses must fall within to be considered a "double-tap".
+
+### Adding a Key Recorder
+
+Use the key command's name to create a key recorder. Then, add it to a view (note the use of ``KeyRecorderView`` for SwiftUI and ``KeyRecorder`` for Cocoa):
+
+#### SwiftUI
 
+```swift
+struct SettingsView: View {
+    var body: some View {
+        KeyRecorderView(name: "ToggleMainWindow")
+    }
+}
+```
+
+#### Cocoa
+
+```swift
+class SettingsViewController: NSViewController {
+    let recorder = KeyRecorder(name: "ToggleMainWindow")
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        view.addSubview(recorder)
+    }
+}
+```
+
+The result should look something like this:
+
+![](recorder-window)
+
+The recorder and command will stay synchronized with each other, so when the user records a new key combination, the command will be updated to match the new value.
+
+---
+
+For improved type safety, you can create hard-coded command names that can be referenced across your app.
+
+`Misc.swift`
 ```swift
 extension KeyCommand.Name {
-    static let showPreferences = Self("ShowPreferences")
+    static let toggleMainWindow = Self("ToggleMainWindow")
 }
-let command = KeyCommand(name: .showPreferences)
 ```
 
-Key commands are automatically stored `UserDefaults`. The name of the command serves as its key. You can provide a custom prefix that will be combined with each name to create the keys.
+`AppDelegate.swift`
+```swift
+let command = KeyCommand(name: .toggleMainWindow)
+```
+
+`SettingsView.swift`
+```swift
+let recorder = KeyRecorder(name: .toggleMainWindow)
+```
+
+---
+
+Key commands are automatically stored in the `UserDefaults` system, using their names as keys. It's common for `UserDefaults` keys to be prefixed, or namespaced, according to their corresponding app or subsystem. To that end, `SwiftKeys` lets you provide custom prefixes that can be applied to individual names.
 
 ```swift
 extension KeyCommand.Name.Prefix {
-    public override var sharedPrefix: Self {
-        Self("SK")
-    }
+    static let settings = Self("Settings")
+    static let app = Self("MyGreatApp")
 }
 
 extension KeyCommand.Name {
-    static let showPreferences = Self("ShowPreferences")
+    // "SettingsOpen" will be the full UserDefaults key.
+    static let openSettings = Self("Open", prefix: .settings)
+
+    // "MyGreatApp_Quit" will be the full UserDefaults key.
+    static let quitApp = Self("Quit", prefix: .app, separator: "_")
 }
-// The name above will become "SKShowPreferences" when used as a defaults key.
 ```
 
 You can find `SwiftKeys` [on GitHub](https://github.com/jordanbaird/SwiftKeys)