diff --git a/gst/gstbufferpool.c b/gst/gstbufferpool.c
index ab212b5ce3..08461b0465 100644
--- a/gst/gstbufferpool.c
+++ b/gst/gstbufferpool.c
@@ -520,6 +520,10 @@ wrong_config:
  * the pool. A default and mandatory set of parameters can be configured with
  * gst_buffer_pool_config_set(). This function takes ownership of @config.
  *
+ * If the parameters in @config can not be set exactly, this function returns
+ * FALSE and will try to update as much state as possible. The new state can
+ * then be retrieved and refined with gst_buffer_pool_config_get().
+ *
  * Returns: TRUE when the configuration could be set.
  */
 gboolean