Add some documentation (#110)

NickEntin · dfed · NickEntin · commit f8ab8ecf3ab9 · 2021-02-21T19:22:10.000-08:00
* Add documentation for logging
* Remove outdated iOS version specification from README
* Clean up files and add missing headerdocs

Co-authored-by: Dan Federman &lt;dfed@me.com&gt;
diff --git a/Documentation/Logging.md b/Documentation/Logging.md
@@ -0,0 +1,90 @@
+# Logging
+
+One of the most helpful components of an actionable bug report is a complete set of logs. Aardvark makes it simple to add logs with the logging utilities in the CoreAardvark framework.
+
+## Getting Started
+
+The easiest way to get started logging with Aardvark is by replacing calls to `print` with `log` in Swift and calls to `NSLog` with `ARKLog` in Objective-C.
+
+```swift
+log("Hello world")
+```
+
+```objc
+ARKLog(@"Hello world");
+```
+
+By default, this will log messages to the Aardvark log store _instead of_ the console. If you would like the messages to be logged to the console as well, toggle the default log store's `printsLogsToConsole` property:
+
+```swift
+ARKLogDistributor.default().defaultLogStore.printsLogsToConsole = true
+```
+
+## Adding Parameters
+
+A recommended pattern for logging is to keep your log messages simple and attach details of the log in the `parameters` field. You can attach key/value pairs of strings to your log messages to provide further debugging data, while keeping your logs easy to scan through in a list of messages.
+
+```swift
+log("Said hello to user", parameters: ["user_name": user.name])
+```
+
+```objc
+ARKLogWithParameters(@{ @"user_name": [user name] }, @"Said hello to user");
+```
+
+## Using Dependency Injection
+
+If you prefer to use dependency injection rather than global functions, you can inject an `ARKLogDistributor` to your logging call sites.
+
+```swift
+func sayHelloToPerson(named name: String, on logDistributor: ARKLogDistributor) {
+    logDistributor.log("Hello \(name)")
+}
+```
+
+```objc
+- (void)sayHelloToPersonNamed:(NSString *)name onLogDistributor:(ARKLogDistributor *)logDistributor;
+{
+    [logDistributor logWithFormat:@"Hello %@", name];
+}
+```
+
+## Using Multiple Log Stores
+
+By default, all logs are sent to the same log file. If you would prefer to send some logs into separate log files, you can add multiple log stores to the distributor and set each store's `logFilterBlock` to filter incoming logs.
+
+To facilitate filtering, log messages contain a `userInfo` dictionary. Unlike the `parameters` dictionary, the `userInfo` is not persisted with the log message.
+
+```swift
+log("Loaded data", userInfo: ["category": "Core Data"])
+```
+
+For example, we can set up a second log store for all of the logs related to Core Data and filter these logs out of the main log store. This could be helpful if our Core Data implementation consistently runs tasks in the background and creates noise in the main log store.
+
+```swift
+// Create the new log store.
+let coreDataLogStore = ARKLogStore(persistedLogFileName: "CoreDataLogs.data")
+
+// Set the new log store to only include logs related to Core Data.
+coreDataLogStore.logFilterBlock = { message in
+    return message.userInfo?["category"] == "Core Data"
+}
+
+// Add the new log store to the default distributor.
+ARKLogDistributor.default().add(coreDataLogStore)
+
+// Set the default log store to exclude log related to Core Data.
+ARKLogDistributor.default().defaultLogStore.logFilterBlock = { message in
+    return !coreDataLogStore.logFilterBlock(message)
+}
+```
+
+See [SampleViewController](../AardvarkSample/AardvarkSample/SampleViewController.swift)’s `tapGestureLogStore` for an example of how this works.
+
+## Sending Logs to Other Services
+
+One log can be easily distributed to multiple services by adding objects conforming to [ARKLogObserver](../Sources/CoreAardvark/Logging/ARKLogObserver.h) to the default [ARKLogDistributor](../Sources/CoreAardvark/Logging/ARKLogDistributor.h) via `addLogObserver:`. [SampleCrashlyticsLogObserver](../AardvarkSample/AardvarkSample/SampleCrashlyticsLogObserver.h) is an example of an [ARKLogObserver](../Sources/CoreAardvark/Logging/ARKLogObserver.h) that sends event logs to Crashlytics.
+
+## Formatting Logs
+
+When logs are shown in the in-app log viewer or attached to a bug report email, they are formatted into plain text. You can change how these messages look by creating a formatter that conforms to [ARKLogFormatter](../Sources/CoreAardvark/Logging/ARKLogFormatter.h) and setting it as the formatter where desired (e.g. as the `logFormatter` on an [ARKEmailBugReporter](../Sources/AardvarkMailUI/ARKEmailBugReporter.h)).
diff --git a/README.md b/README.md
@@ -30,7 +30,6 @@ The easiest way to get Aardvark up and running is to add a dependency on the Aar
 #### Using [CocoaPods](https://cocoapods.org)
 
 ```
-platform :ios, '8.0'
 pod 'AardvarkMailUI'
 ```
 
@@ -64,12 +63,6 @@ In Objective-C:
 
 In Swift, replace calls to `print` with `log`. In Objective-C, replace calls to `NSLog` with `ARKLog`.
 
-By default, this will log messages to the Aardvark log store _instead of_ the console. If you would like the messages to be logged to the console as well, toggle the default log store's `printsLogsToConsole` property:
-
-```swift
-ARKLogDistributor.default().defaultLogStore.printsLogsToConsole = true
-```
-
 ## Reporting Bugs
 
 After doing the above, your users can report a bug by making a two-finger long-press gesture. This gesture triggers a UIAlert asking the user what went wrong. When the user enters this information, an email bug report is generated complete with an attached app screenshot and a text file containing the last 2000 logs. Screenshots are created and stored within Aardvark and do not require camera roll access.
@@ -92,11 +85,7 @@ Once the exception is logged, it will be propogated to any existing uncaught exc
 
 Want to customize how bug reports are filed? Pass your own object conforming to the [ARKBugReporter](Sources/Aardvark/Bug%20Reporting/ARKBugReporter.h) protocol and the desired subclass of `UIGestureRecognizer` to `[Aardvark addBugReporter:triggeringGestureRecognizerClass:]`. You can further customize how bug reports will be triggered by modifying the returned gesture recognizer.
 
-Want to change how logs are formatted? Set your own `logFormatter` on the [ARKEmailBugReporter](Sources/AardvarkMailUI/ARKEmailBugReporter.h) returned from `[Aardvark addDefaultBugReportingGestureWithEmailBugReporterWithRecipient:]`.
-
-Want different log files for different features? Create an [ARKLogStore](Sources/CoreAardvark/Logging/ARKLogStore.h) for each feature you want to have its own log file and add them to the default log distributor with `[[ARKLogDistributor defaultDistributor] addLogObserver:featureLogStore]`. Set the `logFilterBlock` on your [ARKLogStore](Sources/CoreAardvark/Logging/ARKLogStore.h) to make sure only the logs you want are observed by the [ARKLogStore](Sources/CoreAardvark/Logging/ARKLogStore.h). Use `ARKLogWithType`’s `userInfo` dictionary to specify to which feature a log pertains. See [SampleViewController](AardvarkSample/AardvarkSample/SampleViewController.swift)’s `tapGestureLogStore` for an example.
-
-Want to send your logs to third party services? One log can be easily distributed to multiple services by adding objects conforming to [ARKLogObserver](Sources/CoreAardvark/Logging/ARKLogObserver.h) to the default [ARKLogDistributor](Sources/CoreAardvark/Logging/ARKLogDistributor.h) via `addLogObserver:`. [SampleCrashlyticsLogObserver](AardvarkSample/AardvarkSample/SampleCrashlyticsLogObserver.h) is an example of an [ARKLogObserver](Sources/CoreAardvark/Logging/ARKLogObserver.h) that sends event logs to Crashlytics.
+Want to change how logs are formatted? Or use different log files for different features? Or send your logs to third party services? Check out the [logging documentation](Documentation/Logging.md).
 
 Want to log with Aardvark but don’t want to use Aardvark’s bug reporting tool? Change the dependency to be on `Aardvark` and skip step #2 in the Getting Started guide.
 
diff --git a/Sources/Aardvark/Aardvark.swift b/Sources/Aardvark/Aardvark.swift
@@ -17,27 +17,38 @@
 import CoreAardvark
 import Foundation
 
-
 public typealias EmailAddress = String
 
 @objc
 public class Aardvark : NSObject {
-    
-    /// Creates and returns a gesture recognizer that when triggered will call [bugReporter composeBugReport].
+
+    /// Creates and returns a gesture recognizer that when triggered will call `bugReporter.composeBugReport()`.
     @nonobjc
-    public static func add<GestureRecognizer: UIGestureRecognizer>(bugReporter: ARKBugReporter, triggeringGestureRecognizerClass: GestureRecognizer.Type) -> GestureRecognizer? {
-        return UIApplication.shared.add(bugReporter: bugReporter, triggeringGestureRecognizerClass: triggeringGestureRecognizerClass)
+    public static func add<GestureRecognizer: UIGestureRecognizer>(
+        bugReporter: ARKBugReporter,
+        triggeringGestureRecognizerClass: GestureRecognizer.Type
+    ) -> GestureRecognizer? {
+        return UIApplication.shared.add(
+            bugReporter: bugReporter,
+            triggeringGestureRecognizerClass: triggeringGestureRecognizerClass
+        )
     }
-    
-    /// Creates and returns a gesture recognizer that when triggered will call [bugReporter composeBugReport].
+
+    /// Creates and returns a gesture recognizer that when triggered will call `bugReporter.composeBugReport()`.
     @objc(addBugReporter:gestureRecognizerClass:)
-    public static func objc_add(bugReporter: ARKBugReporter, triggeringGestureRecognizerClass gestureRecognizerClass: AnyClass) -> AnyObject? {
+    public static func objc_add(
+        bugReporter: ARKBugReporter,
+        triggeringGestureRecognizerClass gestureRecognizerClass: AnyClass
+    ) -> AnyObject? {
         guard let triggeringGestureRecognizerClass = gestureRecognizerClass as? UIGestureRecognizer.Type else {
             noteImproperAPIUse("\(gestureRecognizerClass) is not a gesture recognizer class!")
             return nil
         }
-        
-        return UIApplication.shared.add(bugReporter: bugReporter, triggeringGestureRecognizerClass: triggeringGestureRecognizerClass)
+
+        return UIApplication.shared.add(
+            bugReporter: bugReporter,
+            triggeringGestureRecognizerClass: triggeringGestureRecognizerClass
+        )
     }
 }
 
diff --git a/Sources/Aardvark/UIApplication+ARKAdditions.swift b/Sources/Aardvark/UIApplication+ARKAdditions.swift
@@ -16,104 +16,124 @@
 
 import Foundation
 
-
 extension UIApplication {
+
     @nonobjc
     private static var observingKeyWindowNotifications = false
 
     @nonobjc
     private static let bugReporterToGestureRecognizerMap: NSMapTable<ARKBugReporter, UIGestureRecognizer> = NSMapTable.strongToStrongObjects()
-    
-    /// Creates and returns a gesture recognizer that when triggered will call [bugReporter composeBugReport]. Must be called from the main thread.
+
+    /// Creates and returns a gesture recognizer that when triggered will call `bugReporter.composeBugReport()`. Must be
+    /// called from the main thread.
     @nonobjc
-    func add<GestureRecognizer: UIGestureRecognizer>(bugReporter: ARKBugReporter, triggeringGestureRecognizerClass: GestureRecognizer.Type) -> GestureRecognizer? {
+    func add<GestureRecognizer: UIGestureRecognizer>(
+        bugReporter: ARKBugReporter,
+        triggeringGestureRecognizerClass: GestureRecognizer.Type
+    ) -> GestureRecognizer? {
         guard Thread.isMainThread else {
             noteImproperAPIUse("Must call \(#function) from the main thread!")
             return nil
         }
-        
+
         guard bugReporter.logStores().count > 0 else {
             noteImproperAPIUse("Attempting to add a bug reporter without a log store!")
             return nil
         }
-        
-        let bugReportingGestureRecognizer = triggeringGestureRecognizerClass.init(target: self, action: #selector(UIApplication.didFire(bugReportGestureRecognizer:)))
+
+        let bugReportingGestureRecognizer = triggeringGestureRecognizerClass.init(
+            target: self,
+            action: #selector(UIApplication.didFire(bugReportGestureRecognizer:))
+        )
         keyWindow?.addGestureRecognizer(bugReportingGestureRecognizer)
-        
+
         UIApplication.bugReporterToGestureRecognizerMap.setObject(bugReportingGestureRecognizer, forKey: bugReporter)
-        
+
         if !UIApplication.observingKeyWindowNotifications {
-            NotificationCenter.default.addObserver(self, selector: #selector(windowDidBecomeKey(notification:)), name: UIWindow.didBecomeKeyNotification, object: nil)
-            NotificationCenter.default.addObserver(self, selector: #selector(windowDidResignKey(notification:)), name: UIWindow.didResignKeyNotification, object: nil)
-            
+            NotificationCenter.default.addObserver(
+                self,
+                selector: #selector(windowDidBecomeKey(notification:)),
+                name: UIWindow.didBecomeKeyNotification,
+                object: nil
+            )
+            NotificationCenter.default.addObserver(
+                self,
+                selector: #selector(windowDidResignKey(notification:)),
+                name: UIWindow.didResignKeyNotification,
+                object: nil
+            )
+
             UIApplication.observingKeyWindowNotifications = true
         }
-        
+
         return bugReportingGestureRecognizer
     }
 
     @nonobjc
     func remove(bugReporter: ARKBugReporter) {
-        if let gestureRecognizerToRemove: UIGestureRecognizer = UIApplication.bugReporterToGestureRecognizerMap.object(forKey: bugReporter) {
+        if let gestureRecognizerToRemove = UIApplication.bugReporterToGestureRecognizerMap.object(forKey: bugReporter) {
             gestureRecognizerToRemove.view?.removeGestureRecognizer(gestureRecognizerToRemove)
-            
+
             UIApplication.bugReporterToGestureRecognizerMap.removeObject(forKey: bugReporter)
         }
     }
-    
+
     @objc(ARK_didFireBugReportGestureRecognizer:)
     private func didFire(bugReportGestureRecognizer: UIGestureRecognizer) {
         guard bugReportGestureRecognizer.state == .began else {
             return
         }
-        
+
         var bugReporters = [ARKBugReporter]()
         for bugReporter in UIApplication.bugReporterToGestureRecognizerMap.keyEnumerator() {
-            guard let bugReporter = bugReporter as? ARKBugReporter, !bugReporters.contains(where: { $0 === bugReporter }) else {
+            guard
+                let bugReporter = bugReporter as? ARKBugReporter,
+                !bugReporters.contains(where: { $0 === bugReporter })
+            else {
                 continue
             }
-            
+
             let recognizerForBugReport = UIApplication.bugReporterToGestureRecognizerMap.object(forKey: bugReporter)
             if recognizerForBugReport === bugReportGestureRecognizer {
                 bugReporters.append(bugReporter)
             }
         }
-        
+
         guard bugReporters.count > 0 else {
             return
         }
-        
+
         for bugReporter in bugReporters {
             bugReporter.composeBugReport()
         }
     }
-    
+
     @objc(ARK_windowDidBecomeKeyNotification:)
     private func windowDidBecomeKey(notification: Notification) {
         guard let window = notification.object as? UIWindow else {
             return
         }
-        guard let gestureRecognizersEnumerator = UIApplication.bugReporterToGestureRecognizerMap.objectEnumerator() else {
+        guard let enumerator = UIApplication.bugReporterToGestureRecognizerMap.objectEnumerator() else {
             return
         }
-        
-        for gestureRecognizer in gestureRecognizersEnumerator {
+
+        for gestureRecognizer in enumerator {
             if let gestureRecognizer = gestureRecognizer as? UIGestureRecognizer {
                 window.addGestureRecognizer(gestureRecognizer)
             }
         }
     }
-    
+
     @objc(ARK_windowDidResignKeyNotification:)
     private func windowDidResignKey(notification: Notification) {
         guard let window = notification.object as? UIWindow else {
             return
         }
-        guard let gestureRecognizersEnumerator = UIApplication.bugReporterToGestureRecognizerMap.objectEnumerator() else {
+        guard let enumerator = UIApplication.bugReporterToGestureRecognizerMap.objectEnumerator() else {
             return
         }
-        
-        for gestureRecognizer in gestureRecognizersEnumerator {
+
+        for gestureRecognizer in enumerator {
             if let gestureRecognizer = gestureRecognizer as? UIGestureRecognizer {
                 window.removeGestureRecognizer(gestureRecognizer)
             }
diff --git a/Sources/CoreAardvark/Logging/ARKLogMessage.h b/Sources/CoreAardvark/Logging/ARKLogMessage.h
@@ -39,11 +39,19 @@
 - (nonnull instancetype)init NS_UNAVAILABLE;
 + (nonnull instancetype)new NS_UNAVAILABLE;
 
+/// The date at which the message was logged.
 @property (nonnull, nonatomic, copy, readonly) NSDate *date;
+
+/// The text of the log message.
 @property (nonnull, nonatomic, copy, readonly) NSString *text;
+
+/// An optional image associated with the log message. Typically used for logs of type `ARKLogTypeScreenshot`.
 @property (nullable, nonatomic, readonly) UIImage *image;
+
+/// The type of the log message.
 @property (nonatomic, readonly) ARKLogType type;
 
+/// Details about the log message. This data is persisted.
 @property (nonnull, nonatomic, copy, readonly) NSDictionary<NSString *, NSString *> *parameters;
 
 /// Arbitrary information that can be used by ARKLogObserver objects. This data is not persisted.
diff --git a/Sources/CoreAardvark/Logging/Logging.swift b/Sources/CoreAardvark/Logging/Logging.swift
@@ -16,13 +16,27 @@
 
 import Foundation
 
-
+/// Logs a new messages to the default Aardvark log distributor.
+///
+/// - parameter text: The text of the log message.
+/// - parameter type: The type of log message.
+/// - parameter image: An optional image to be attached to the log message. Typically used for messages of type
+///                    `.screenshot`.
+/// - parameter parameters: A set of key/value pairs that is persisted with the log message.
+/// - parameter userInfo: A set of key/value pairs that is _not_ persisted with the log message, but rather can be
+///                       used to control how the message is processed by various log observers.
 public func log(
     _ text: String,
     type: ARKLogType = .`default`,
     image: UIImage? = nil,
     parameters: [String : String] = [:],
     userInfo: [NSObject : AnyObject]? = nil
 ) {
-    ARKLogDistributor.default().log(withText: text, image: image, type: type, parameters: parameters, userInfo: userInfo);
+    ARKLogDistributor.default().log(
+        withText: text,
+        image: image,
+        type: type,
+        parameters: parameters,
+        userInfo: userInfo
+    )
 }
