Add comments for FailureHandler functions

app/src/main/java/org/unifiedpush/distributor/nextpush/services/FailureHandler.kt

@@ -19,11 +19,16 @@ object FailureHandler {
     // This is the last eventSource opened
     private val eventSource: AtomicReference<EventSource?> = AtomicReference(null)
 
+    /**
+     * Is the [eventSource] the current one?
+     * Any eventSource is considered as the current if none is saved.
+     */
     private fun isCurrentEventSource(eventSource: EventSource?): Boolean {
         return this.eventSource.get()?.let {
             it == eventSource
         } ?: true
     }
+
     fun newEventSource(context: Context, eventSource: EventSource) {
         Log.d(TAG, "newEvent/Eventsource: $eventSource")
         this.eventSource.getAndSet(eventSource)?.cancel()
@@ -40,8 +45,20 @@ object FailureHandler {
         return nFails.get()
     }
 
-    // Returns true if the fail is from the current eventSource
-    fun newFail(context: Context, eventSource: EventSource?): Boolean {
+    /**
+     * Check the [eventSource] and increase the counter of failed events.
+     *
+     * If this is the 2nd error, we show a notification to inform the user.
+     *
+     * If the connection has correctly started but we haven't received a ping,
+     * we increase the counter of failed events before ping.
+     *
+     * Removes and cancel the current [eventSource].
+     * If this is not the current eventSource, we close it.
+     *
+     * @return `true` if the fail is from the current eventSource
+     */
+    fun newFail(context: Context, eventSource: EventSource): Boolean {
         Log.d(TAG, "newFail/Eventsource: $eventSource")
         // ignore fails from a possible old eventSource
         // if we are already reconnected
@@ -61,7 +78,7 @@ object FailureHandler {
             true
         } else {
             Log.d(TAG, "This is an old EventSource.")
-            eventSource?.cancel()
+            eventSource.cancel()
             false
         }
     }
@@ -84,6 +101,11 @@ object FailureHandler {
         this.eventSource.getAndSet(null)?.cancel()
     }
 
+    /**
+     * Is the service started and and has already failed once ?
+     *
+     * If [orNeverStart] is true (default) we consider a non-started service as a failed service
+     */
     fun hasFailed(orNeverStart: Boolean = true): Boolean {
         // nFails > 0 to be sure it is not actually restarting
         return if (orNeverStart) { eventSource.get() == null } else { false } || nFails.get() > 0