Add KDoc on ActivityLifecycleEvent explaining ordering semantics.

Also, a couple of minor fixes:
- A small warning on `RibActivity` against importing `android.R`.
- Replaces deprecated `String.toLowerCase()` and `String.capitalize()` with the equivalent `String.lowercase()` and `String.replaceFirstChar(Char::titlecase)`.

android/libraries/rib-android/src/main/kotlin/com/uber/rib/core/RibActivity.kt

@@ -17,7 +17,6 @@
 
 package com.uber.rib.core
 
-import android.R
 import android.content.Intent
 import android.content.res.Configuration
 import android.os.Build
@@ -91,7 +90,7 @@ abstract class RibActivity :
   @CallSuper
   override fun onCreate(savedInstanceState: android.os.Bundle?) {
     super.onCreate(savedInstanceState)
-    val rootViewGroup = findViewById<ViewGroup>(R.id.content)
+    val rootViewGroup = findViewById<ViewGroup>(android.R.id.content)
     _lifecycleFlow.tryEmit(createOnCreateEvent(savedInstanceState))
     val wrappedBundle: Bundle? =
       if (savedInstanceState != null) Bundle(savedInstanceState) else null

android/libraries/rib-android/src/main/kotlin/com/uber/rib/core/lifecycle/ActivityLifecycleEvent.kt

@@ -17,7 +17,34 @@ package com.uber.rib.core.lifecycle
 
 import android.os.Bundle
 
-/** Lifecycle events that can be emitted by Activities. */
+/**
+ * Lifecycle events that can be emitted by Activities.
+ *
+ * ### Ordering semantics
+ *
+ * This class implements [Comparable], but it does **not** override `equals`, so even though the
+ * following holds:
+ * ```
+ * val a = createOnCreateEvent(null)
+ * val b = createOnCreateEvent(Bundle())
+ * assertThat(a <= b).isTrue()
+ * assertThat(b <= a).isTrue()
+ * ```
+ *
+ * The equality does not hold:
+ * ```
+ * assertThat(a == b).isFalse()
+ * ```
+ *
+ * This happens because events of type [CREATE][ActivityLifecycleEvent.Type.CREATE] hold a [Bundle],
+ * and even though any two `CREATE` events are equal in ordering ([compareTo]), they are never equal
+ * in [equals] comparison.
+ *
+ * In mathematical terms, the activity events set form a
+ * [total preorder](https://en.wikipedia.org/wiki/Weak_ordering#Total_preorders), but *not* a
+ * [total order](https://en.wikipedia.org/wiki/Total_order): it is reflexive, transitive, strongly
+ * connected, but **not** antisymmetric.
+ */
 open class ActivityLifecycleEvent
 private constructor(
   /** @return this event's type. */
@@ -37,7 +64,10 @@ private constructor(
 
   override fun compareTo(other: ActivityLifecycleEvent): Int = type.compareTo(other.type)
 
-  /** An [ActivityLifecycleEvent] that encapsulates information from [Activity.onCreate]. */
+  /**
+   * An [ActivityLifecycleEvent] that encapsulates information from
+   * [Activity.onCreate][android.app.Activity.onCreate].
+   */
   open class Create(
     /** @return this event's savedInstanceState data. */
     open val savedInstanceState: Bundle?,
@@ -79,7 +109,7 @@ private constructor(
         Type.DESTROY -> DESTROY_EVENT
         else ->
           throw IllegalArgumentException(
-            "Use the createOn${type.name.toLowerCase().capitalize()}Event() method for this type!",
+            "Use the createOn${type.name.lowercase().replaceFirstChar(Char::titlecase)}Event() method for this type!",
           )
       }
     }