pad: more documentation regarding the new flags

diff --git a/gst/gstpad.c b/gst/gstpad.c
index 222a563..6808bfc 100644 (file)
--- a/gst/gstpad.c
+++ b/gst/gstpad.c
@@ -2007,6 +2007,12 @@ done:
  *
  * Links the source pad and the sink pad.
  *
+ * This variant of #gst_pad_link provides a more granular control on the
+ * checks being done when linking. While providing some considerable speedups
+ * the caller of this method must be aware that wrong usage of those flags
+ * can cause severe issues. Refer to the documentation of #GstPadLinkCheck
+ * for more information.
+ *
  * Returns: A result code indicating if the connection worked or
  *          what went wrong.
  *

diff --git a/gst/gstpad.h b/gst/gstpad.h
index 7f1870a..d2a10a4 100644 (file)
--- a/gst/gstpad.h
+++ b/gst/gstpad.h
@@ -179,14 +179,19 @@ GQuark                    gst_flow_to_quark       (GstFlowReturn ret);
 
 /**
  * GstPadLinkCheck:
- * @GST_PAD_LINK_CHECK_NOTHING: Don't check hierarchy or compatibily
- * @GST_PAD_LINK_CHECK_HIERARCHY: Check the pads have same parents/grandparents
+ * @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 checking their full 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.
+ *
  * Since: 0.10.30
  */