Documentation update (#25)

* Add comments in public definitions
* Add table of contents to `README.md`
* Rename `userAttributes` to `attributes`
* Update example projects
* Update Backtrace.podspec

Author: krml19

Backtrace.podspec

@@ -9,7 +9,7 @@
 Pod::Spec.new do |s|
 
   s.name         = "Backtrace"
-  s.version      = "1.4.0"
+  s.version      = "1.4.1"
   s.summary      = "Backtrace's integration with iOS and macOS"
   s.description  = "Backtrace's integration with iOS and macOS for handling crashes"
   s.homepage     = "https://backtrace.io/"

Example-iOS/AppDelegate.swift

@@ -32,7 +32,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 
         BacktraceClient.shared = try? BacktraceClient(configuration: backtraceConfiguration)
         BacktraceClient.shared?.delegate = self
-        BacktraceClient.shared?.userAttributes = ["foo": "bar", "testing": true]
+        BacktraceClient.shared?.attributes = ["foo": "bar", "testing": true]
 
         do {
             try throwingFunc()

Example-macOS-ObjC/AppDelegate.m

@@ -26,7 +26,7 @@ - (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
                                                    reportsPerMin: 3
                                                    allowsAttachingDebugger: TRUE];
     BacktraceClient.shared = [[BacktraceClient alloc] initWithConfiguration: configuration error: nil];
-    [BacktraceClient.shared setUserAttributes: @{@"foo": @"bar"}];
+    [BacktraceClient.shared setAttributes: @{@"foo": @"bar"}];
     BacktraceClient.shared.delegate = self;
 
     @try {

README.md

@@ -77,18 +77,32 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 
     }
 
-    //sending NSError
-    NSError *error = [NSError errorWithDomain: @"backtrace.domain" code: 100 userInfo: @{}];
-    [[BacktraceClient shared] sendWithCompletion:^(BacktraceResult * _Nonnull result) {
-        NSLog(@"%@", result);
-    }];
-
     return YES;
 }
 
 @end
 ```
 
+# Table of contents
+1. [Features Summary](#features-summary)
+2. [Installation](#installation)
+    * [Cocoapods](#installation-cocoapods)
+3. [Documentation](#documentation)
+    1. [Initialize client](#documentation-client-initialization)
+    2. [Configure client](#documentation-client-configuration)
+        * [Database settings](#documentation-database-settings)
+    3. [Events handling](#documentation-events-handling)
+    4. [Attributes](#documentation-attributes)
+    5. [Attachments](#documentation-attachments)
+    6. [Sending reports](#documentation-sending-report)
+        1. [Error/NSError](#documentation-sending-error)
+        2. [NSException](#documentation-sending-exception)
+        3. [macOS note](#documentatio-sending-report-macOS)
+4. [FAQ](#faq)
+    1. [Missing dSYM files](#faq-missing-dsym)
+        * [Finding dSYMs while building project](#faq-finding-dsym-building)
+        * [Finding dSYMs while archiving project](#faq-finding-dsym-archiving)
+
 # Features Summary <a name="features-summary"></a>
 * Light-weight client library written in Swift with full Objective-C support that quickly submits exceptions/errors and crashes to your Backtrace dashboard includes:
   * system metadata,
@@ -102,7 +116,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 
 # Installation <a name="installation"></a>
 
-## via CocoaPods
+## via CocoaPods <a name="installation-cocoapods"></a>
 
 To use [CocoaPods](https://cocoapods.org) just add this to your Podfile:
 
@@ -112,11 +126,10 @@ pod 'Backtrace'
 
 **Note:** It is required to specify `use_frameworks!` in your Podfile.
 
-# Documentation  <a name="documentation"></a>
-
-## Register with Backtrace credentials<a name="documentation-initialization"></a>
+# Documentation <a name="documentation"></a>
 
-Register to Backtrace services using provided submission url (see: <a href="https://help.backtrace.io/troubleshooting/what-is-a-submission-url">What is a submission url?</a>) and token (see: <a href="https://help.backtrace.io/troubleshooting/what-is-a-submission-token">What is a submission token?</a>).
+## Initialize Backtrace client <a name="documentation-client-initialization"></a>
+Initializing Backtrace clinet requires registration to Backtrace services. You can register to Backtrace services using provided submission url (see: <a href="https://help.backtrace.io/troubleshooting/what-is-a-submission-url">What is a submission url?</a>) and token (see: <a href="https://help.backtrace.io/troubleshooting/what-is-a-submission-token">What is a submission token?</a>). These credentials you can supply using `BacktraceCredentials`.
 
 - Swift
 ```swift
@@ -127,8 +140,8 @@ BacktraceClient.shared = try? BacktraceClient(credentials: BacktraceCredentials)
 BacktraceClient.shared = [[BacktraceClient alloc] initWithCredentials: BacktraceCredentials error: error];
 ```
 
-## Backtrace client configuration
-For more advanced usage of BacktraceClient, you can supply BacktraceClientConfiguration as a parameter. See the following example:
+## Configure Backtrace client <a name="documentation-client-configuration"></a>
+For more advanced usage of `BacktraceClient`, you can supply `BacktraceClientConfiguration` as a parameter. See the following example:
 - Swift
 ```swift
 let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!, token: "token")
@@ -156,7 +169,7 @@ BacktraceClient.shared = [[BacktraceClient alloc] initWithConfiguration: configu
 
 **Note:** Backtrace library will *not* send any reports if the `allowsAttachingDebugger` flag is set to `false`.
 
-### Database settings
+### Database settings <a name="documentation-database-settings"></a>
 BacktraceClient allows you to customize the initialization of BacktraceDatabase for local storage of error reports by supplying a BacktraceDatabaseSettings parameter, as follows:
 
 - Swift
@@ -198,8 +211,8 @@ BacktraceClientConfiguration *configuration = [[BacktraceClientConfiguration all
 BacktraceClient.shared = [[BacktraceClient alloc] initWithConfiguration: configuration error: nil];
 ```
 
-### Events handling
-`BacktraceClient` allows you to subscribe for events produced before and after sending each report.
+## Events handling <a name="documentation-events-handling"></a>
+`BacktraceClient` allows you to subscribe for events produced before and after sending each report. You have to only attach object which confirm to `BacktraceClientDelegate` protocol.
 - Swift
 ```swift
 // assign `self` or any other object as a `BacktraceClientDelegate`
@@ -225,20 +238,38 @@ BacktraceClient.shared.delegate = self;
 - (NSURLRequest *)willSendRequest:(NSURLRequest *)request;
 - (void)didReachLimit:(BacktraceResult *)result;
 ```
+Attaching `BacktraceClientDelegate` allows you to e.g. modify report before send:
+- Swift
+```swift
+func willSend(_ report: BacktraceReport) -> (BacktraceReport) {
+    report.attributes["added"] = "just before send"
+    return report
+}
+```
+- Objctive-C
+```objective-c
+- (BacktraceReport *)willSend:(BacktraceReport *)report {
+    NSMutableDictionary *dict = [report.attributes mutableCopy];
+    [dict setObject: @"just before send" forKey: @"added"];
+    report.attributes = dict;
+    return report;
+}
+```
 
-### User attributes
-You can add custom user attributes that should be send alongside crash and erros/exceptions:
+## Attributes <a name="documentation-attributes"></a>
+You can add custom attributes that should be send alongside crash and erros/exceptions:
 - Swift
 ```swift
-BacktraceClient.shared?.userAttributes = ["foo": "bar", "testing": true]
+BacktraceClient.shared?.attributes = ["foo": "bar", "testing": true]
 ```
 
 - Objective-C
 ```objective-c
-BacktraceClient.shared.userAttributes = @{@"foo": @"bar", @"testing": YES};
+BacktraceClient.shared.attributes = @{@"foo": @"bar", @"testing": YES};
 ```
+Set attributes are attached to each report. You can specify unique set of attributes for specific report in `willSend(_:)` method of `BacktraceClientDelegate`. See [events handling](#documentation-events-handling) for more information.
 
-### Attachments
+## Attachments <a name="documentation-attachments"></a>
 For each report you can attach files by supplying an array of file paths.
 - Swift
 ```swift
@@ -254,11 +285,12 @@ NSArray *paths = @[[[NSBundle mainBundle] pathForResource: @"test" ofType: @"txt
     NSLog(@"%@", result);
 }];
 ```
+Supplied files are attached for each report. You can specify unique set of files for specific report in `willSend(_:)` method of `BacktraceClientDelegate`. See [events handling](#documentation-events-handling) for more information.
 
 ## Sending an error report <a name="documentation-sending-report"></a>
 Registered `BacktraceClient` will be able to send an crash reports. Error report is automatically generated based.
 
-### Sending `Error/NSError`
+### Sending `Error/NSError` <a name="documentation-sending-error"></a>
 - Swift
 ```swift
 @objc func send(completion: ((BacktraceResult) -> Void))
@@ -268,7 +300,7 @@ Registered `BacktraceClient` will be able to send an crash reports. Error report
  - (void) sendWithCompletion: (void (^)(BacktraceResult * _Nonnull)) completion;
 ```
 
-### Sending `NSException`
+### Sending `NSException` <a name="documentation-sending-exception"></a>
 - Swift
 ```swift
 @objc func send(exception: NSException, completion: ((BacktraceResult) -> Void))
@@ -278,36 +310,36 @@ Registered `BacktraceClient` will be able to send an crash reports. Error report
  - (void) sendWithException: NSException completion: (void (^)(BacktraceResult * _Nonnull)) completion;
 ```
 
-### macOS note
+### macOS note <a name="documentatio-sending-report-macOS"></a>
 If you want to catch additional exceptions on macOS which are not forwarded by macOS runtime, set `NSPrincipalClass` to `Backtrace.BacktraceCrashExceptionApplication` in your `Info.plist`.
 
 Alternatively, you can set:
-- Swift 
+- Swift
 ```swift
 UserDefaults.standard.register(defaults: ["NSApplicationCrashOnExceptions": true])
 ```
--Objective-C
+- Objective-C
 ```objective-c
 [[NSUserDefaults standardUserDefaults] registerDefaults:@{ @"NSApplicationCrashOnExceptions": @YES }];
 ```
 but it crashes your app if you don't use `@try ... @catch`.
 
-# FAQ
-## Missing dSYM files
+# FAQ <a name="faq"></a>
+## Missing dSYM files <a name="faq-missing-dsym"></a>
 Make sure your project is configured to generate the debug symbols:
 * Go to your project target's build settings: `YourTarget -> Build Settings`.
 * Search for `Debug Information Format`.
 * Select `DWARF with dSYM File`.
 ![alt text](https://github.com/backtrace-labs/backtrace-cocoa/blob/master/docs/screenshots/xcode-debug-information-format.png)
 
-### Finding dSYMs while building project
+### Finding dSYMs while building project <a name="faq-finding-dsym-building"></a>
 * Build the project.
 * Build products and dSYMs are placed into the `Products` directory.
 ![alt text](https://github.com/backtrace-labs/backtrace-cocoa/blob/master/docs/screenshots/xcode-products.png)
 ![alt text](https://github.com/backtrace-labs/backtrace-cocoa/blob/master/docs/screenshots/finder-dsyms-products.png)
 * Zip all the `dSYM` files and upload to Backtrace services (see: <a href="https://help.backtrace.io/product-guide/symbolification">Symbolification</a>)
 
-### Finding dSYMs while archiving project
+### Finding dSYMs while archiving project <a name="faq-finding-dsym-archiving"></a>
 * Archive the project.
 * dSYMs are placed inside of an `.xcarchive` of your project.
 * Open Xcode -> Window -> Organizer

Sources/Features/Attributes/AttributesProvider.swift

@@ -3,7 +3,7 @@ import Foundation
 final class AttributesProvider {
 
     // attributes can be modified on runtime
-    var userAttributes: Attributes = [:]
+    var attributes: Attributes = [:]
 
     private let bluetoothStatusListener = BluetoothStatusListener()
     private var faultMessage: String?
@@ -14,8 +14,8 @@ extension AttributesProvider: SignalContext {
         self.faultMessage = faultMessage
     }
 
-    var attributes: Attributes {
-        return userAttributes + defaultAttributes
+    var allAttributes: Attributes {
+        return attributes + defaultAttributes
     }
 
     var defaultAttributes: Attributes {
@@ -28,6 +28,6 @@ extension AttributesProvider: SignalContext {
 
 extension AttributesProvider: CustomStringConvertible {
     var description: String {
-        return attributes.compactMap { "\($0.key): \($0.value)"}.joined(separator: "\n")
+        return allAttributes.compactMap { "\($0.key): \($0.value)"}.joined(separator: "\n")
     }
 }

Sources/Features/Client/BacktraceReporter.swift

@@ -52,11 +52,11 @@ extension BacktraceReporter: BacktraceClientCustomizing {
         }
     }
 
-    var userAttributes: Attributes {
+    var attributes: Attributes {
         get {
-            return attributesProvider.userAttributes
+            return attributesProvider.attributes
         } set {
-            attributesProvider.userAttributes = newValue
+            attributesProvider.attributes = newValue
         }
     }
 }
@@ -79,7 +79,7 @@ extension BacktraceReporter {
               faultMessage: String? = nil) throws -> BacktraceResult {
         attributesProvider.set(faultMessage: faultMessage)
         let resource = try reporter.generateLiveReport(exception: exception,
-                                                       attributes: attributesProvider.attributes,
+                                                       attributes: attributesProvider.allAttributes,
                                                        attachmentPaths: attachmentPaths)
         return try send(resource: resource)
     }

Sources/Features/Crash Reporting/CrashReporter.swift

@@ -21,7 +21,7 @@ extension CrashReporter: CrashReporting {
                 }
                 BacktraceLogger.debug("Saving custom attributes:\n\(attributesProvider.description)")
                 attributesProvider.set(faultMessage: "siginfo_t.si_signo: \(signalInfo.si_signo)")
-                try? AttributesStorage.store(attributesProvider.attributes, fileName: CrashReporter.crashName)
+                try? AttributesStorage.store(attributesProvider.allAttributes, fileName: CrashReporter.crashName)
         }
         var callbacks = PLCrashReporterCallbacks(version: 0, context: rawMutablePointer, handleSignal: handler)
         reporter.setCrash(&callbacks)

Sources/Features/Repository/Model/BacktraceReport.swift

@@ -1,12 +1,19 @@
 import Foundation
 import Backtrace_PLCrashReporter
 
+/// Model represents single crash report which can be send to Backtrace services.
 @objc final public class BacktraceReport: NSObject {
 
+    /// Encoded informations about report like stack trace etc.
     @objc public let reportData: Data
+    
     let plCrashReport: PLCrashReport
     let identifier: UUID
+    
+    /// Array of files paths attached to the report.
     @objc public var attachmentPaths: [String]
+    
+    /// `Attributes` attached to the report.
     @objc public var attributes: Attributes
 
     init(report: Data, attributes: Attributes, attachmentPaths: [String]) throws {

Sources/Public/BacktraceClient.swift

@@ -63,13 +63,13 @@ extension BacktraceClient: BacktraceClientCustomizing {
         }
     }
 
-    /// Additional user attributes which are automatically added to each report.
-    @objc public var userAttributes: Attributes {
+    /// Additional attributes which are automatically added to each report.
+    @objc public var attributes: Attributes {
         get {
-            return reporter.userAttributes
+            return reporter.attributes
         }
         set {
-            reporter.userAttributes = newValue
+            reporter.attributes = newValue
         }
     }
 }

Sources/Public/BacktraceClientConfiguration.swift

@@ -3,32 +3,36 @@ import Foundation
 /// Backtrace client configuration settings.
 @objc public class BacktraceClientConfiguration: NSObject {
 
-    /// Client's credentials.
+    /// Client's credentials. To learn more about credentials, see
+    /// https://help.backtrace.io/troubleshooting/what-is-a-submission-url
+    /// and https://help.backtrace.io/troubleshooting/what-is-a-submission-token .
     @objc public let credentials: BacktraceCredentials
 
     /// Database settings
     @objc public var dbSettings: BacktraceDatabaseSettings = BacktraceDatabaseSettings()
 
-    /// Number of records sent in 1 minute. Default: 3.
+    /// Number of records sent in 1 minute. Default `3`.
     @objc public var reportsPerMin: Int = 3
 
-    /// Flag indicating if the Backtrace client should raport reports when the debugger is attached.
+    /// Flag indicating if the Backtrace client should raport reports when the debugger is attached. Default `false`.
     @objc public var allowsAttachingDebugger: Bool = false
 
     /// Produces Backtrace client configuration settings.
+    ///
     /// - Parameters:
     ///   - credentials: Backtrace server API credentials.
     @objc public init(credentials: BacktraceCredentials) {
         self.credentials = credentials
     }
 
     /// Produces Backtrace client configuration settings.
+    ///
     /// - Parameters:
     ///   - credentials: Backtrace server API credentials.
-    ///   - dbSettings: Backtrace database settings
-    ///   - reportsPerMin: Maximum number of records sent to Backtrace services in 1 minute. Default: 3
+    ///   - dbSettings: Backtrace database settings.
+    ///   - reportsPerMin: Maximum number of records sent to Backtrace services in 1 minute. Default: `3`.
     ///   - allowsAttachingDebugger: if set to `true` BacktraceClient will report reports even when the debugger
-    /// is attached. Default: `false`
+    /// is attached. Default: `false`.
     @objc public init(credentials: BacktraceCredentials,
                       dbSettings: BacktraceDatabaseSettings = BacktraceDatabaseSettings(),
                       reportsPerMin: Int = 3,