- * A #GstPromise can be created with gst_promise_new(), replied to
- * with gst_promise_reply(), interrupted with gst_promise_interrupt() and
- * expired with gst_promise_expire(). A callback can also be installed at
- * #GstPromise creation for result changes with gst_promise_new_with_change_func().
+ * A #GstPromise is created with gst_promise_new() by the consumer and passed
+ * to the producer to avoid thread safety issues with the change callback.
+ * A #GstPromise can be replied to with a value (or an error) by the producer
+ * with gst_promise_reply(). gst_promise_interrupt() is for the consumer to
+ * indicate to the producer that the value is not needed anymore and producing
+ * that value can stop. The @GST_PROMISE_RESULT_EXPIRED state set by a call
+ * to gst_promise_expire() indicates to the consumer that a value will never
+ * be produced and is intended to be called by a third party that implements
+ * some notion of message handling such as #GstBus.
+ * A callback can also be installed at #GstPromise creation for
+ * result changes with gst_promise_new_with_change_func().