From 0ce166c005b32712cf4ff8a0e957c72e61af4259 Mon Sep 17 00:00:00 2001
From: Andreas Linde <mail@andreaslinde.de>
Date: Sat, 17 Aug 2013 14:57:58 +0200
Subject: [PATCH] Document some more BITCrashManager methods

---
 Classes/BITCrashManager.m | 83 +++++++++++++++++++++++++++++++++++----
 1 file changed, 75 insertions(+), 8 deletions(-)

diff --git a/Classes/BITCrashManager.m b/Classes/BITCrashManager.m
index 9f15655653..6f3a97ea05 100644
--- a/Classes/BITCrashManager.m
+++ b/Classes/BITCrashManager.m
@@ -163,6 +163,11 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
 
 #pragma mark - Private
 
+/**
+ * Save all settings
+ *
+ * This saves the list of approved crash reports
+ */
 - (void)saveSettings {
   NSString *errorString = nil;
   
@@ -180,6 +185,11 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
   }
 }
 
+/**
+ * Load all settings
+ *
+ * This contains the list of approved crash reports
+ */
 - (void)loadSettings {
   NSString *errorString = nil;
   NSPropertyListFormat format;
@@ -202,6 +212,9 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
   }
 }
 
+/**
+ *	 Remove all crash reports and stored meta data for each from the file system and keychain
+ */
 - (void)cleanCrashReports {
   NSError *error = NULL;
   
@@ -218,6 +231,16 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
   [self saveSettings];
 }
 
+/**
+ *	 Extract all app sepcific UUIDs from the crash reports
+ * 
+ * This allows us to send the UUIDs in the XML construct to the server, so the server does not need to parse the crash report for this data.
+ * The app specific UUIDs help to identify which dSYMs are needed to symbolicate this crash report.
+ *
+ *	@param	report The crash report from PLCrashReporter
+ *
+ *	@return XML structure with the app sepcific UUIDs
+ */
 - (NSString *) extractAppUUIDs:(BITPLCrashReport *)report {
   NSMutableString *uuidString = [NSMutableString string];
   NSArray *uuidArray = [BITCrashReportTextFormatter arrayOfAppUUIDsForCrashReport:report];
@@ -235,6 +258,11 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
   return uuidString;
 }
 
+/**
+ *	 Get the userID from the delegate which should be stored with the crash report
+ *
+ *	@return The userID value
+ */
 - (NSString *)userIDForCrashReport {
   NSString *userID = @"";
   
@@ -248,6 +276,11 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
   return userID;
 }
 
+/**
+ *	 Get the userName from the delegate which should be stored with the crash report
+ *
+ *	@return The userName value
+ */
 - (NSString *)userNameForCrashReport {
   NSString *username = @"";
   
@@ -266,6 +299,11 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
   return username;
 }
 
+/**
+ *	 Get the userEmail from the delegate which should be stored with the crash report
+ *
+ *	@return The userEmail value
+ */
 - (NSString *)userEmailForCrashReport {
   NSString *useremail = @"";
 
@@ -286,7 +324,11 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
 
 #pragma mark - PLCrashReporter
 
-// Called to handle a pending crash report.
+/**
+ *	 Process new crash reports provided by PLCrashReporter
+ *
+ * Parse the new crash report and gather additional meta data from the app which will be stored along the crash report
+ */
 - (void) handleCrashReport {
   BITPLCrashReporter *crashReporter = [BITPLCrashReporter sharedReporter];
   NSError *error = NULL;
@@ -355,6 +397,11 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
   [crashReporter purgePendingCrashReport];
 }
 
+/**
+ *	Check if there are any crash reports available which the user did not approve yet
+ *
+ *	@return `YES` if there are crash reports pending that are not approved, `NO` otherwise
+ */
 - (BOOL)hasNonApprovedCrashReports {
   if (!_approvedCrashReports || [_approvedCrashReports count] == 0) return YES;
   
@@ -367,6 +414,11 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
   return NO;
 }
 
+/**
+ *	Check if there are any new crash reports that are not yet processed
+ *
+ *	@return	`YES` if ther eis at least one new crash report found, `NO` otherwise
+ */
 - (BOOL)hasPendingCrashReport {
   if (_crashManagerStatus == BITCrashManagerStatusDisabled) return NO;
     
@@ -406,7 +458,13 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
 
 #pragma mark - Crash Report Processing
 
-// slightly delayed startup processing, so we don't keep the first runloop on startup busy for too long
+/**
+ * Delayed startup processing for everything that does not to be done in the app startup runloop
+ *
+ * - Checks if there is another exception handler installed that may block ours
+ * - Present UI if the user has to approve new crash reports
+ * - Send pending approved crash reports
+ */
 - (void)invokeDelayedProcessing {
   BITHockeyLog(@"INFO: Start delayed CrashManager processing");
   
@@ -463,7 +521,9 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
   }
 }
 
-// begin the startup process
+/**
+ *	 Main startup sequence initializing PLCrashReporter if it wasn't disabled
+ */
 - (void)startManager {
   if (_crashManagerStatus == BITCrashManagerStatusDisabled) return;
   
@@ -521,12 +581,12 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
   [self performSelector:@selector(invokeDelayedProcessing) withObject:nil afterDelay:0.5];
 }
 
+/**
+ *	 Send all approved crash reports
+ *
+ * Gathers all collected data and constructs the XML structure and starts the sending process
+ */
 - (void)sendCrashReports {
-  // send it to the next runloop
-  [self performSelector:@selector(performSendingCrashReports) withObject:nil afterDelay:1.0f];
-}
-
-- (void)performSendingCrashReports {
   NSError *error = NULL;
 	  
   NSMutableString *crashes = nil;
@@ -670,6 +730,13 @@ NSString *const kBITCrashManagerStatus = @"BITCrashManagerStatus";
 
 #pragma mark - Networking
 
+/**
+ *	 Send the XML data to the server
+ *
+ * Wraps the XML structure into a POST body and starts sending the data asynchronously
+ *
+ *	@param	xml	The XML data that needs to be send to the server
+ */
 - (void)postXML:(NSString*)xml {
   NSMutableURLRequest *request = nil;
   NSString *boundary = @"----FOO";