pad: Document that pad blocks only make sense for sink pads in pull mode and src...

See bug #644907.

diff --git a/gst/gstpad.c b/gst/gstpad.c
index 4276471..e517e25 100644 (file)
--- a/gst/gstpad.c
+++ b/gst/gstpad.c
@@ -1033,6 +1033,11 @@ gst_pad_is_active (GstPad * pad)
  * You can pass NULL as the callback to make this call block. Be careful with
  * this blocking call as it might not return for reasons stated above.
  *
+ * <note>
+ *  Pad block handlers are only called for source pads in push mode
+ *  and sink pads in pull mode.
+ * </note>
+ *
  * Returns: TRUE if the pad could be blocked. This function can fail if the
  * wrong parameters were passed or the pad was already in the requested state.
  *
@@ -1127,6 +1132,11 @@ had_right_state:
  * take an indeterminate amount of time.
  * You can pass NULL as the callback to make this call block. Be careful with
  * this blocking call as it might not return for reasons stated above.
+ * 
+ * <note>
+ *  Pad block handlers are only called for source pads in push mode
+ *  and sink pads in pull mode.
+ * </note>
  *
  * Returns: TRUE if the pad could be blocked. This function can fail if the
  * wrong parameters were passed or the pad was already in the requested state.
@@ -1150,6 +1160,11 @@ gst_pad_set_blocked_async (GstPad * pad, gboolean blocked,
  * a shortcut for gst_pad_set_blocked_async() with a NULL
  * callback.
  *
+ * <note>
+ *  Pad blocks are only possible for source pads in push mode
+ *  and sink pads in pull mode.
+ * </note>
+ *
  * Returns: TRUE if the pad could be blocked. This function can fail if the
  * wrong parameters were passed or the pad was already in the requested state.
  *