DOCS: explicitly mention that property observing has an initial event

This is definitely intended from the start, and it's generally useful,
but for some reason it wasn't actually documented.

2 files changed, 9 insertions, 2 deletions

diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index 7be8960915..d3034f1113 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -344,12 +344,16 @@ The ``mp`` module is preloaded, although it can be loaded manually with
     exact behavior depends on timing and other things.)
 
     In some cases the function is not called even if the property changes.
-    Whether this can happen depends on the property.
+    This depends on the property, and it's a valid feature request to ask for
+    better update handling of a specific property.
 
     If the ``type`` is ``none`` or ``nil``, sporadic property change events are
     possible. This means the change function ``fn`` can be called even if the
     property doesn't actually change.
 
+    You always get an initial change notification. This is meant to initialize
+    the user's state to the current value of the property.
+
 ``mp.unobserve_property(fn)``
     Undo ``mp.observe_property(..., fn)``. This removes all property handlers
     that are equal to the ``fn`` parameter. This uses normal Lua ``==``
diff --git a/libmpv/client.h b/libmpv/client.h
index 8a9f1f7368..36c9d8584a 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -1197,6 +1197,9 @@ int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata,
  * 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.
  *
+ * You always get an initial change notification. This is meant to initialize
+ * the user's state to the current value of the property.
+ *
  * 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.
@@ -1209,7 +1212,7 @@ int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata,
  * 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
+ * will have to determine yourself whether the property really changed. 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