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

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.

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:

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)

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

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 *