Renamed LeafDependent.pull to LeafDependent.dependenciesChanged and added some documentation.

cell/src/commonMain/kotlin/world/phantasmal/cell/CallbackChangeObserver.kt

@@ -11,7 +11,7 @@ class CallbackChangeObserver<T, E : ChangeEvent<T>>(
     // We don't use ChangeObserver<T> because of type system limitations. It would break e.g.
     // AbstractListCell.observeListChange.
     private val callback: (E) -> Unit,
-) : TrackedDisposable(), Dependent, LeafDependent {
+) : TrackedDisposable(), LeafDependent {
 
     init {
         dependency.addDependent(this)
@@ -26,7 +26,7 @@ class CallbackChangeObserver<T, E : ChangeEvent<T>>(
         MutationManager.invalidated(this)
     }
 
-    override fun pull() {
+    override fun dependenciesChanged() {
         // See comment above callback property to understand why this is safe.
         dependency.changeEvent?.let(unsafeCast<(ChangeEvent<T>) -> Unit>(callback))
     }

cell/src/commonMain/kotlin/world/phantasmal/cell/CallbackObserver.kt

@@ -8,7 +8,7 @@ import world.phantasmal.core.disposable.TrackedDisposable
 class CallbackObserver(
     private vararg val dependencies: Cell<*>,
     private val callback: () -> Unit,
-) : TrackedDisposable(), Dependent, LeafDependent {
+) : TrackedDisposable(), LeafDependent {
 
     init {
         for (dependency in dependencies) {
@@ -28,7 +28,7 @@ class CallbackObserver(
         MutationManager.invalidated(this)
     }
 
-    override fun pull() {
+    override fun dependenciesChanged() {
         var changed = false
 
         // We loop through all dependencies to ensure they're valid again.

cell/src/commonMain/kotlin/world/phantasmal/cell/Dependency.kt

@@ -1,7 +1,13 @@
 package world.phantasmal.cell
 
+/**
+ * This interface is not meant to be implemented by typical application code.
+ */
 interface Dependency<out T> {
-    // TODO: Docs.
+    /**
+     * This property is not meant to be accessed from typical application code. The current change
+     * event for this dependency. Only valid during a mutation.
+     */
     val changeEvent: ChangeEvent<T>?
 
     /**

cell/src/commonMain/kotlin/world/phantasmal/cell/Dependent.kt

@@ -1,13 +1,14 @@
 package world.phantasmal.cell
 
+/**
+ * This interface is not meant to be implemented by typical application code.
+ */
 interface Dependent {
     /**
-     * TODO: Fix documentation.
      * This method is not meant to be called from typical application code.
      *
      * Called whenever a dependency of this dependent might change. Sometimes a dependency doesn't
-     * know that it will actually change, just that it might change. Always call [dependencyChanged]
-     * after calling this method.
+     * know that it will actually change, just that it might change.
      *
      * E.g. C depends on B and B depends on A. A is about to change, so it calls
      * [dependencyInvalidated] on B. At this point B doesn't know whether it will actually change
@@ -17,7 +18,14 @@ interface Dependent {
     fun dependencyInvalidated(dependency: Dependency<*>)
 }
 
-interface LeafDependent {
-    // TODO: Sensible name for `pull`.
-    fun pull()
+/**
+ * This interface is not meant to be implemented by typical application code.
+ */
+interface LeafDependent : Dependent {
+    /**
+     * This method is not meant to be called from typical application code. Called by
+     * [MutationManager] when invalidation notifications have finished propagating, the current
+     * outer mutation is ending and leaves should be updated.
+     */
+    fun dependenciesChanged()
 }

cell/src/commonMain/kotlin/world/phantasmal/cell/MutationManager.kt

@@ -24,7 +24,7 @@ object MutationManager {
     private var artificialMutation = false
 
     private var dependencyChanging = false
-    private var pulling = false
+    private var notifyingLeavesOfChanges = false
 
     private val deferredMutations: MutableList<() -> Unit> = mutableListOf()
     private var applyingDeferredMutations = false
@@ -53,7 +53,9 @@ object MutationManager {
 
     fun mutationStart() {
         assert(!dependencyChanging) { "Can't start a mutation while a dependency is changing." }
-        assert(!pulling) { "Can't start a mutation while pulling." }
+        assert(!notifyingLeavesOfChanges) {
+            "Can't start a mutation while notifying leaf dependents of changes."
+        }
 
         if (mutationNestingLevel == 0) {
             currentMutationId++
@@ -66,17 +68,17 @@ object MutationManager {
         assert(mutationNestingLevel > 0) { "No mutation was started." }
 
         if (mutationNestingLevel == 1) {
-            assert(!pulling) { "Already pulling." }
+            assert(!notifyingLeavesOfChanges) { "Already notifying leaf dependents of changes." }
 
             try {
-                pulling = true
+                notifyingLeavesOfChanges = true
 
                 for (dependent in invalidatedLeaves) {
-                    dependent.pull()
+                    dependent.dependenciesChanged()
                 }
             } finally {
                 dependencyChanging = false
-                pulling = false
+                notifyingLeavesOfChanges = false
                 mutationNestingLevel--
                 invalidatedLeaves.clear()
                 applyDeferredMutations()
@@ -103,7 +105,9 @@ object MutationManager {
 
     fun dependencyChangeStart() {
         check(!dependencyChanging) { "A cell is already changing." }
-        assert(!pulling) { "Can't change a cell while pulling." }
+        assert(!notifyingLeavesOfChanges) {
+            "Can't change a cell while  notifying leaf dependents of changes."
+        }
 
         if (mutationNestingLevel == 0) {
             mutationStart()