pulse: Document the operation state behavior on context disconnection.

src/pulse/def.h

@@ -93,9 +93,14 @@ static inline int PA_STREAM_IS_GOOD(pa_stream_state_t x) {
 
 /** The state of an operation */
 typedef enum pa_operation_state {
-    PA_OPERATION_RUNNING,      /**< The operation is still running */
-    PA_OPERATION_DONE,         /**< The operation has been completed */
-    PA_OPERATION_CANCELLED     /**< The operation has been cancelled. Before 0.9.18 this was called PA_OPERATION_CANCELED. That name is still available for compatibility. */
+    PA_OPERATION_RUNNING,
+    /**< The operation is still running */
+    PA_OPERATION_DONE,
+    /**< The operation has been completed */
+    PA_OPERATION_CANCELLED
+    /**< The operation has been cancelled. Operations may get cancelled by the
+     * application, or as a result of the context getting disconneted while the
+     * operation is pending. */
 } pa_operation_state_t;
 
 /** \cond fulldocs */

src/pulse/operation.h

@@ -53,8 +53,12 @@ void pa_operation_cancel(pa_operation *o);
 /** Return the current status of the operation */
 pa_operation_state_t pa_operation_get_state(pa_operation *o);
 
-/** Set the callback function that is called when the operation
- * is canceled due to disconnection. \since 4.0 */
+/** Set the callback function that is called when the operation state
+ * changes. Usually this is not necessary, since the functions that
+ * create pa_operation objects already take a callback that is called
+ * when the operation finishes. Registering a state change callback is
+ * mainly useful, if you want to get called back also if the operation
+ * gets cancelled. \since 4.0 */
 void pa_operation_set_state_callback(pa_operation *o, pa_operation_notify_cb_t cb, void *userdata);
 
 PA_C_DECL_END