client API: improve mpv_observe_property docs

Document the "normal" behavior (if MPV_FORMAT_NONE is not used) first,
and then introduce MPV_FORMAT_NONE as exception.

The actual semantics didn't change in mpv; this is only clarification.

1 files changed, 18 insertions, 11 deletions

diff --git a/libmpv/client.h b/libmpv/client.h
index 54b4718155..fe7efa66f8 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -779,37 +779,44 @@ int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata,
 /**
  * Get a notification whenever the given property changes. You will receive
  * updates as MPV_EVENT_PROPERTY_CHANGE. Note that this is not very precise:
- * it can send updates even if the property in fact did not change, or (in
- * some cases) not send updates even if the property changed - it usually
- * depends on the property. It's a valid feature request to ask for better
- * update handling of a specific property.
+ * for some properties, it may not send updates even if the property changed.
+ * This depends on the property, and it's a valid feature request to ask for
+ * better update handling of a specific property. (For some properties, like
+ * ``clock``, which shows the wall clock, this mechanism doesn't make too
+ * much sense anyway.)
  *
  * Property changes are coalesced: the change events are returned only once the
  * event queue becomes empty (e.g. mpv_wait_event() would block or return
  * MPV_EVENT_NONE), and then only one event per changed property is returned.
  *
- * If the format parameter is set to something other than MPV_FORMAT_NONE, the
- * current property value will be returned as part of mpv_event_property. In
- * this case, the API will also suppress redundant change events by comparing
- * the raw value against the previous value.
+ * Normally, change events are sent only if the property value changes according
+ * to the requested format. mpv_event_property will contain the property value
+ * as data member.
  *
  * Warning: if a property is unavailable or retrieving it caused an error,
  *          MPV_FORMAT_NONE will be set in mpv_event_property, even if the
  *          format parameter was set to a different value. In this case, the
  *          mpv_event_property.data field is invalid.
  *
- * Observing a property that doesn't exist is allowed, although it may still
- * cause some sporadic change events.
+ * If the property is observed with the format parameter set to MPV_FORMAT_NONE,
+ * you get low-level notifications whether the property _may_ have changed, and
+ * the data member in mpv_event_property will be unset. With this mode, you
+ * will have to determine yourself whether the property really changd. On the
+ * other hand, this mechanism can be faster and uses less resources.
+ *
+ * Observing a property that doesn't exist is allowed. (Although it may still
+ * cause some sporadic change events.)
  *
  * Keep in mind that you will get change notifications even if you change a
  * property yourself. Try to avoid endless feedback loops, which could happen
- * if you react to change notifications which you caused yourself.
+ * if you react to the change notifications triggered by your own change.
  *
  * @param reply_userdata This will be used for the mpv_event.reply_userdata
  *                       field for the received MPV_EVENT_PROPERTY_CHANGE
  *                       events. (Also see section about asynchronous calls,
  *                       although this function is somewhat different from
  *                       actual asynchronous calls.)
+ *                       If you have no use for this, pass 0.
  *                       Also see mpv_unobserve_property().
  * @param name The property name.
  * @param format see enum mpv_format. Can be MPV_FORMAT_NONE to omit values