gst/: Add note about refcounting and miniobject/buffer writeability to docs. Fixes...

Original commit message from CVS:
* gst/gstbuffer.h:
* gst/gstminiobject.c:
Add note about refcounting and miniobject/buffer writeability
to docs. Fixes #340604
* gst/gstelementfactory.h:
Added some explanation about @klass.

diff --git a/ChangeLog b/ChangeLog
index 6ce9b0d..a8edd3d 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2006-05-05  Wim Taymans  <wim@fluendo.com>
+
+       * gst/gstbuffer.h:
+       * gst/gstminiobject.c:
+       Add note about refcounting and miniobject/buffer writeability
+       to docs. Fixes #340604
+
+       * gst/gstelementfactory.h:
+       Added some explanation about @klass.
+
 2006-05-05  Maciej Katafiasz  <mathrick@freedesktop.org>
 
        * docs/manual/intro-motivation.xml:

diff --git a/gst/gstbuffer.h b/gst/gstbuffer.h
index 6213c23..77ffd5d 100644 (file)
--- a/gst/gstbuffer.h
+++ b/gst/gstbuffer.h
@@ -286,6 +286,14 @@ G_STMT_START {                                             \
  * @buf: a #GstBuffer.
  *
  * Increases the refcount of the given buffer by one.
+ *
+ * Note that the refcount affects the writeability
+ * of @buf, see gst_buffer_is_writable(). It is
+ * important to note that keeping additional references to
+ * GstBuffer instances can potentially increase the number
+ * of memcpy operations in a pipeline.
+ *
+ * Returns: @buf
  */
 static inline GstBuffer *
 gst_buffer_ref (GstBuffer * buf)

diff --git a/gst/gstelementfactory.h b/gst/gstelementfactory.h
index b66396a..a5b89a5 100644 (file)
--- a/gst/gstelementfactory.h
+++ b/gst/gstelementfactory.h
@@ -41,12 +41,15 @@ typedef struct _GstElementDetails GstElementDetails;
 /**
  * GstElementDetails:
  * @longname: long, english name
- * @klass: type of element, as hierarchy
+ * @klass: type of element, as an unordered list separated with slashes ('/')
  * @description: what the element is about
  * @author: who wrote this thing?
  *
  * This struct defines the public information about a #GstElement. It contains
  * meta-data about the element that is mostly for the benefit of editors.
+ *
+ * The @klass member can be used by applications to filter elements based 
+ * on functionality.
  */
 /* FIXME: need translatable stuff in here (how handle in registry)? */
 struct _GstElementDetails

diff --git a/gst/gstminiobject.c b/gst/gstminiobject.c
index 279ec73..660d4c8 100644 (file)
--- a/gst/gstminiobject.c
+++ b/gst/gstminiobject.c
@@ -232,6 +232,13 @@ gst_mini_object_make_writable (GstMiniObject * mini_object)
  *
  * Increase the reference count of the mini-object.
  *
+ * Note that the refcount affects the writeability
+ * of @mini-object, see gst_mini_object_is_writable(). It is 
+ * important to note that keeping additional references to
+ * GstMiniObject instances can potentially increase the number
+ * of memcpy operations in a pipeline, especially if the minibject
+ * is a #GstBuffer.
+ *
  * Returns: the mini-object.
  */
 GstMiniObject *