diff --git a/src/main/java/com/mapconductor/core/OverlayCollector.kt b/src/main/java/com/mapconductor/core/OverlayCollector.kt
index cd986b8..de63ddc 100644
--- a/src/main/java/com/mapconductor/core/OverlayCollector.kt
+++ b/src/main/java/com/mapconductor/core/OverlayCollector.kt
@@ -24,6 +24,11 @@ interface ComponentState {
      * [StateMutationSignal.notifying]. Without that the collector never hears
      * about an in-place change and the renderer keeps drawing the old value —
      * silently, which is why this is required rather than defaulted.
+     *
+     * Only an assignment to a field is reported. Changing the object a field
+     * holds — adding to a list passed in as `points`, say — reaches no one, and
+     * assigning a value equal to the current one is ignored, so re-assigning a
+     * list after editing it in place does nothing either. Assign a new value.
      */
     val mutations: StateMutationSignal
 }
diff --git a/src/main/java/com/mapconductor/core/StateMutationSignal.kt b/src/main/java/com/mapconductor/core/StateMutationSignal.kt
index ae305fb..b1810a2 100644
--- a/src/main/java/com/mapconductor/core/StateMutationSignal.kt
+++ b/src/main/java/com/mapconductor/core/StateMutationSignal.kt
@@ -53,6 +53,11 @@ class StateMutationSignal {
      *
      * Declare `mutations` above the fields that use it: property initialisers
      * run in declaration order, and the other way round it is still null here.
+     *
+     * The field reports assignments to itself and nothing else: an in-place
+     * change to the object it holds (a `MutableList`, a `mutableStateListOf`)
+     * is not seen, and an assignment equal to the current value is dropped.
+     * Callers change such a field by assigning a new value.
      */
     fun <T> notifying(initial: T): MutableState<T> = NotifyingState(mutableStateOf(initial), this)
 }
diff --git a/src/main/java/com/mapconductor/core/polygon/Polygon.kt b/src/main/java/com/mapconductor/core/polygon/Polygon.kt
index 685bbba..97af7c8 100644
--- a/src/main/java/com/mapconductor/core/polygon/Polygon.kt
+++ b/src/main/java/com/mapconductor/core/polygon/Polygon.kt
@@ -60,7 +60,27 @@ class PolygonState(
      */
     var clickable by mutations.notifying(clickable)
     var zIndex by mutations.notifying(zIndex)
+
+    /**
+     * 外周の頂点。
+     *
+     * state が見ているのはこのプロパティへの代入だけ。渡したリストをその場で書き換えても
+     * 描き直されない（`mutableStateListOf` を渡して `add` / `set` する使い方は効かない）。
+     * 形を変えるときは新しいリストを代入する:
+     *
+     * ```
+     * polygonState.points = polygonState.points.toMutableList().apply { this[i] = moved }
+     * ```
+     *
+     * 内容の等しいリストの代入は無視される。その場で書き換えた同じリストを代入し直しても、
+     * 前の値と同じものなので何も起きない。
+     */
     var points by mutations.notifying<List<GeoPointInterface>>(points)
+
+    /**
+     * 穴（内周）の頂点。[points] と同じく、変えるときは新しいリストを代入する。
+     * 内側のリストをその場で書き換えても描き直されない。
+     */
     var holes by mutations.notifying<List<List<GeoPointInterface>>>(holes)
     var extra by mutations.notifying(extra)
     var onClick by mutations.notifying(onClick)
diff --git a/src/main/java/com/mapconductor/core/polyline/Polyline.kt b/src/main/java/com/mapconductor/core/polyline/Polyline.kt
index 45b97bc..5885be0 100644
--- a/src/main/java/com/mapconductor/core/polyline/Polyline.kt
+++ b/src/main/java/com/mapconductor/core/polyline/Polyline.kt
@@ -55,6 +55,21 @@ class PolylineState(
      */
     var clickable by mutations.notifying(clickable)
     var zIndex by mutations.notifying(zIndex)
+
+    /**
+     * 線の頂点。
+     *
+     * state が見ているのはこのプロパティへの代入だけ。渡したリストをその場で書き換えても
+     * 描き直されない（`mutableStateListOf` を渡して `add` / `set` する使い方は効かない）。
+     * 形を変えるときは新しいリストを代入する:
+     *
+     * ```
+     * polylineState.points = polylineState.points + nextPoint
+     * ```
+     *
+     * 内容の等しいリストの代入は無視される。その場で書き換えた同じリストを代入し直しても、
+     * 前の値と同じものなので何も起きない。
+     */
     var points by mutations.notifying<List<GeoPointInterface>>(points)
     var extra by mutations.notifying(extra)
     var onClick by mutations.notifying(onClick)
diff --git a/src/main/java/com/mapconductor/core/raster/RasterLayer.kt b/src/main/java/com/mapconductor/core/raster/RasterLayer.kt
index c52c3c8..56f4bed 100644
--- a/src/main/java/com/mapconductor/core/raster/RasterLayer.kt
+++ b/src/main/java/com/mapconductor/core/raster/RasterLayer.kt
@@ -40,6 +40,11 @@ class RasterLayerState(
     var zIndex by mutations.notifying(zIndex)
     var userAgent by mutations.notifying(userAgent)
     var debug by mutations.notifying(debug)
+
+    /**
+     * タイル要求に足すヘッダー。変えるときは新しい Map を代入する。渡した Map をその場で
+     * 書き換えても state には伝わらず、内容の等しい Map の代入は無視される。
+     */
     var extraHeaders by mutations.notifying(extraHeaders)
 
     private fun rasterLayerId(hashCodes: List<Int>): Int =