Clarify invocation behavior of mismatch handlers (#1695)

redwood-protocol-guest/src/commonMain/kotlin/app/cash/redwood/protocol/guest/ProtocolMismatchHandler.kt

@@ -26,10 +26,23 @@ import kotlin.jvm.JvmField
  * a newer schema than the other, or if their schemas were changed in an incompatible way.
  */
 public interface ProtocolMismatchHandler {
-  /** Handle a request to process an unknown event [tag] for the specified widget [widgetTag]. */
+  /**
+   * Handle a request to process an unknown event [tag] for the specified widget [widgetTag].
+   *
+   * This function will be invoked every time an unknown event is sent to a widget. For example,
+   * three click events on a widget with no click event will see this function invoked three times.
+   * Use the [widgetTag] and [tag] combination to de-duplicate the callbacks if desired.
+   */
   public fun onUnknownEvent(widgetTag: WidgetTag, tag: EventTag)
 
-  /** Handle an event whose node [id] is unknown. */
+  /**
+   * Handle an event whose node [id] is unknown.
+   *
+   * This function will be invoked every time an event is sent to an unknown widget. For example,
+   * clicking three times on a button that has no corresponding instance will see this function
+   * invoked three times. Use the [id] and [tag] combination to de-duplicate the callbacks
+   * if desired.
+   */
   public fun onUnknownEventNode(id: Id, tag: EventTag)
 
   public companion object {

redwood-protocol-host/src/commonMain/kotlin/app/cash/redwood/protocol/widget/ProtocolMismatchHandler.kt

@@ -29,16 +29,42 @@ import kotlin.native.ObjCName
  */
 @ObjCName("ProtocolMismatchHandler", exact = true)
 public interface ProtocolMismatchHandler {
-  /** Handle a request to create an unknown widget [tag]. */
+  /**
+   * Handle a request to create an unknown widget [tag].
+   *
+   * This function will be invoked every time a widget with an unknown tag is created. For example,
+   * a row containing three unknown widgets will see this function invoked three times.
+   * Use the [tag] to de-duplicate the callbacks if desired.
+   */
   public fun onUnknownWidget(tag: WidgetTag)
 
-  /** Handle a request to create an unknown layout modifier [tag]. */
+  /**
+   * Handle a request to create an unknown layout modifier [tag].
+   *
+   * This function will be invoked every time a modifier with an unknown tag is used. For example,
+   * three widgets each using the unknown modifier will see this function invoked three times.
+   * Modifiers are serialized as a chain, so updating an unrelated modifier in a chain which also
+   * contains an unknown modifier will cause this function to be invoked again.
+   * Use the [tag] to de-duplicate the callbacks if desired.
+   */
   public fun onUnknownModifier(tag: ModifierTag)
 
-  /** Handle a request to manipulate unknown children [tag] for the specified [widgetTag]. */
+  /**
+   * Handle a request to manipulate unknown children [tag] for the specified [widgetTag].
+   *
+   * This function will be invoked every time an operation occurs on unknown children. For example,
+   * three buttons inside an unknown children container will see this function invoked three times.
+   * Use the [widgetTag] and [tag] combination to de-duplicate the callbacks if desired.
+   */
   public fun onUnknownChildren(widgetTag: WidgetTag, tag: ChildrenTag)
 
-  /** Handle a request to set an unknown property [tag] for the specified [widgetTag]. */
+  /**
+   * Handle a request to set an unknown property [tag] for the specified [widgetTag].
+   *
+   * This function will be invoked every time an operation occurs on the property. For example,
+   * a timer updating the unknown property every second will see this function invoked every second.
+   * Use the [widgetTag] and [tag] combination to de-duplicate the callbacks if desired.
+   */
   public fun onUnknownProperty(widgetTag: WidgetTag, tag: PropertyTag)
 
   public companion object {