docs: improve the api docs for new GstPadLinkChecks and its use

diff --git a/gst/gstpad.h b/gst/gstpad.h
index d2a10a4..fc7a3c2 100644 (file)
--- a/gst/gstpad.h
+++ b/gst/gstpad.h
@@ -181,16 +181,24 @@ GQuark                    gst_flow_to_quark       (GstFlowReturn ret);
  * GstPadLinkCheck:
  * @GST_PAD_LINK_CHECK_NOTHING: Don't check hierarchy or caps compatibility.
  * @GST_PAD_LINK_CHECK_HIERARCHY: Check the pads have same parents/grandparents.
- * @GST_PAD_LINK_CHECK_TEMPLATE_CAPS: Check if the pads are compatible by using their
- * template caps.
- * @GST_PAD_LINK_CHECK_CAPS: Check if the pads are compatible by comparing the caps
- * returned by #gst_pad_get_caps.
- *
- * The amount of check to be done when linking pads.
- *
- * Warning: Only use these flags if you are 100% certain you know the link will
- * not fail because of hierarchy/caps failures. If uncertain, use the default
- * checks (#GST_PAD_LINK_CHECK_DEFAULT) or the regular methods.
+ *   Could be omitted if it is already known that the two elements that own the
+ *   pads are in the same bin. 
+ * @GST_PAD_LINK_CHECK_TEMPLATE_CAPS: Check if the pads are compatible by using
+ *   their template caps. This is much faster than @GST_PAD_LINK_CHECK_CAPS, but
+ *   would be unsafe e.g. if one pad has %GST_CAPS_ANY.
+ * @GST_PAD_LINK_CHECK_CAPS: Check if the pads are compatible by comparing the
+ *   caps returned by gst_pad_get_caps().
+ *
+ * The amount of checking to be done when linking pads. @GST_PAD_LINK_CHECK_CAPS
+ * and @GST_PAD_LINK_CHECK_TEMPLATE_CAPS are mutually exclusive. If both are
+ * specified, expensive but safe @GST_PAD_LINK_CHECK_CAPS are performed.
+ *
+ * <warning><para>
+ * Only disable some of the checks if you are 100% certain you know the link
+ * will not fail because of hierarchy/caps compatibility failures. If uncertain,
+ * use the default checks (%GST_PAD_LINK_CHECK_DEFAULT) or the regular methods
+ * for linking the pads.
+ * </para></warning>
  *
  * Since: 0.10.30
  */
@@ -205,7 +213,8 @@ typedef enum {
 /**
  * GST_PAD_LINK_CHECK_DEFAULT:
  *
- * The default checks done when linking pads (i.e. the ones used by #gst_pad_link.
+ * The default checks done when linking pads (i.e. the ones used by 
+ * gst_pad_link()).
  *
  * Since: 0.10.30
  */

diff --git a/gst/gstutils.c b/gst/gstutils.c
index 45d61ed..456d53b 100644 (file)
--- a/gst/gstutils.c
+++ b/gst/gstutils.c
@@ -1565,6 +1565,10 @@ pad_link_maybe_ghosting (GstPad * src, GstPad * sink, GstPadLinkCheck flags)
  * child of the parent of the other element.  If they have different
  * parents, the link fails.
  *
+ * Calling gst_element_link_pads_full() with @flags == %GST_PAD_LINK_CHECK_DEFAULT
+ * is the same as calling gst_element_link_pads() and the recommended way of
+ * linking pads with safety checks applied.
+ *
  * Returns: TRUE if the pads could be linked, FALSE otherwise.
  *
  * Since: 0.10.30