docs: improve the seeking docs more.

Also mention it on _element_seek{,_simple} and be more precise why it happens.

diff --git a/gst/gstelement.c b/gst/gstelement.c
index f12e89b..60864a6 100644 (file)
--- a/gst/gstelement.c
+++ b/gst/gstelement.c
@@ -1523,10 +1523,10 @@ gst_element_default_send_event (GstElement * element, GstEvent * event)
  * This function takes owership of the provided event so you should
  * gst_event_ref() it if you want to reuse the event after this call.
  *
- * Returns: %TRUE if the event was handled. Events that execute asynchronously
- * (such as flushing seeks) will emit %GST_MESSAGE_ASYNC_DONE.
- *
  * MT safe.
+ *
+ * Returns: %TRUE if the event was handled. Events that trigger a preroll (such
+ * as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE.
  */
 gboolean
 gst_element_send_event (GstElement * element, GstEvent * event)
@@ -1565,9 +1565,10 @@ gst_element_send_event (GstElement * element, GstEvent * event)
  * the parameters. The seek event is sent to the element using
  * gst_element_send_event().
  *
- * Returns: %TRUE if the event was handled.
- *
  * MT safe.
+ *
+ * Returns: %TRUE if the event was handled. Flushing seeks will trigger a
+ * preroll, which will emit %GST_MESSAGE_ASYNC_DONE.
  */
 gboolean
 gst_element_seek (GstElement * element, gdouble rate, GstFormat format,

diff --git a/gst/gstutils.c b/gst/gstutils.c
index 7771862..90f69f9 100644 (file)
--- a/gst/gstutils.c
+++ b/gst/gstutils.c
@@ -2364,8 +2364,8 @@ gst_element_query_convert (GstElement * element, GstFormat src_format,
  * PAUSED. If the element supports seek in READY, it will always return %TRUE when
  * it receives the event in the READY state.
  *
- * Returns: %TRUE if the seek operation succeeded (the seek might not always be
- * executed instantly though)
+ * Returns: %TRUE if the seek operation succeeded. Flushing seeks will trigger a
+ * preroll, which will emit %GST_MESSAGE_ASYNC_DONE.
  *
  * Since: 0.10.7
  */