 */
 
 
+/**
+    `Analytics` provides a means of capturing analytics data and sending the data to the Bluemix server.
+
+    When this class's `enabled` property is set to `true` (which is the default value), all analytics data will be persisted to a file on the client device in the following JSON format:
+
+        {
+            "timestamp"    : "17-02-2013 13:54:27:123",     // "dd-MM-yyyy hh:mm:ss:S"
+            "level"        : "ANALYTICS",
+            "pkg"          : "mfpsdk.analytics",
+            "msg"          : "",                            // Always an empty string for Analytics logs
+            "metadata"     : {"some key": "some value"}     // Analytics data
+        }
+
+    Analytics data are accumulated persistently to the log file until the file size is greater than the `Logger.maxLogStoreSize` property. At this point, half of the old logs will be deleted to make room for new log data.
+
+    Log file data is sent to the Bluemix server when this class's send() method is called, provided that the file is not empty and the BMSClient was initialized via the `initializeWithBluemixAppRoute()` method. When the log data is successfully uploaded, the persisted local log data is deleted.
+*/
 public class Analytics {
     
     
     // MARK: Properties (public)
     
+    /// Determines whether analytics logs will be persisted to file.
     public static var enabled: Bool = true
     
     

    
    internal static let logger = Logger.getLoggerForName(MFP_ANALYTICS_PACKAGE)
    
    internal static var lifecycleEvents: [String: AnyObject] = [:]
    
    
    
    // MARK: Methods (public)
    
    public static func log(metadata: [String: AnyObject]) {
        
        logger.analytics(metadata)
    }
    
    
    public static func send(completionHandler: MfpCompletionHandler? = nil) {
        
        Logger.sendAnalytics(completionHandler: completionHandler)
    }
    
    
    dynamic static internal func logSessionStart() {
        
        if !lifecycleEvents.isEmpty {

    }
    
    
    // Log that the app session is ending, and use the timer from logSessionStart() to record the duration of this session
    // This method should be called when the closes.
    //      In iOS, this occurs when the app enters the background.
    //      In WatchOS, the user decides when this method is executed, but we recommend calling it when the app becomes active.
    dynamic static internal func logSessionEnd() {
        
        // logSessionStart() must have been called first so that we can get the session start time
        guard !lifecycleEvents.isEmpty else {
            logger.warn("The current app session ended before the start event was triggered, so the session cannot be recorded.")
            return
        }
        
        // If the guard statement above passes, this if statement should always succeed
        if let startTime = lifecycleEvents[KEY_EVENT_START_TIME] as? NSTimeInterval {
            let sessionDuration = NSDate.timeIntervalSinceReferenceDate() - startTime
            lifecycleEvents[KEY_METADATA_DURATION] = sessionDuration
            lifecycleEvents.removeValueForKey(KEY_EVENT_START_TIME)
            
            logger.analytics(lifecycleEvents)
