Add documentation to EnroTestRule and runEnroTest, extract these to t…

…heir own files.

enro-test/src/main/java/dev/enro/test/EnroTest.kt

@@ -8,9 +8,6 @@ import dev.enro.core.controller.NavigationApplication
 import dev.enro.core.controller.NavigationController
 import dev.enro.core.controller.createUnattachedNavigationController
 import dev.enro.viewmodel.EnroViewModelNavigationHandleProvider
-import org.junit.rules.TestRule
-import org.junit.runner.Description
-import org.junit.runners.model.Statement
 
 object EnroTest {
 
@@ -68,21 +65,3 @@ object EnroTest {
     }
 }
 
-fun runEnroTest(block: () -> Unit) {
-    EnroTest.installNavigationController()
-    try {
-        block()
-    } finally {
-        EnroTest.uninstallNavigationController()
-    }
-}
-
-class EnroTestRule : TestRule {
-    override fun apply(base: Statement, description: Description): Statement {
-        return object : Statement() {
-            override fun evaluate() {
-                runEnroTest { base.evaluate() }
-            }
-        }
-    }
-}

enro-test/src/main/java/dev/enro/test/EnroTestRule.kt

@@ -0,0 +1,32 @@
+package dev.enro.test
+
+import org.junit.rules.TestRule
+import org.junit.runner.Description
+import org.junit.runners.model.Statement
+
+/**
+ * The EnroTestRule can be used in both pure JVM based unit tests and instrumented tests that run on devices.
+ *
+ * In both cases, this rule is designed to install a NavigationController that is accessible by
+ * Enro's test extensions, and allow [TestNavigationHandles] to be created, which will record
+ * navigation instructions that are made against the navigation handle. The recorded navigation
+ * instructions can then be asserted on, in particular by using extensions such as
+ * [expectOpenInstruction], [assertActive], [assertClosed], [assertOpened] and others.
+ *
+ * When EnroTestRule is used in an instrumented test, it will *prevent* regular navigation from
+ * occurring, and is designed for testing individual screens in isolation from one another. If you
+ * want to perform "real" navigation in instrumented tests, you do not need any Enro test extensions.
+ *
+ * If you have other TestRules, particularly those that launch Activities or Fragments, you may need
+ * to order this TestRule as the first in the sequence, as the rule will need to be executed before
+ * an Activity or Fragment under test has been instantiated.
+ */
+class EnroTestRule : TestRule {
+    override fun apply(base: Statement, description: Description): Statement {
+        return object : Statement() {
+            override fun evaluate() {
+                runEnroTest { base.evaluate() }
+            }
+        }
+    }
+}

enro-test/src/main/java/dev/enro/test/runEnroTest.kt

@@ -0,0 +1,20 @@
+package dev.enro.test
+
+/**
+ * runEnroTest is a way to perform the same behaviour as that of the EnroTestRule, but without
+ * using a JUnit TestRule. It is designed to wrap the entire block of a test, as in:
+ * ```
+ * @Test
+ * fun exampleTest() = runEnroTest { ... }
+ * ```
+ *
+ * See the documentation for [EnroTestRule] for more information.
+ */
+fun runEnroTest(block: () -> Unit) {
+    EnroTest.installNavigationController()
+    try {
+        block()
+    } finally {
+        EnroTest.uninstallNavigationController()
+    }
+}