added docs for the TAG defines

Original commit message from CVS:
added docs for the TAG defines

ChangeLog

@@ -1,3 +1,14 @@
+2005-01-18  Stefan Kost  <ensonic@users.sf.net>
+
+	* docs/gst/gstreamer-sections.txt:
+	* docs/gst/tmpl/gstplugin.sgml:
+	* docs/libs/gstreamer-libs-sections.txt:
+	* docs/libs/tmpl/gstcontrol.sgml:
+	* gst/gstbuffer.h:
+	* gst/gsttag.h:
+	* gst/gstvalue.c:
+      added docs for the TAG defines
+
 2005-01-18  Ronald S. Bultje  <rbultje@ronald.bitfreak.net>
 
 	* gst/schedulers/gstoptimalscheduler.c: (schedule_group):

docs/gst/gstreamer-sections.txt

@@ -20,6 +20,8 @@ gst_use_threads
 gst_has_threads
 gst_main
 gst_main_quit
+<SUBSECTION Private>
+GstPoptOption
 </SECTION>
 
 <SECTION>

docs/gst/tmpl/gstplugin.sgml

@@ -6,18 +6,19 @@ Container for features loaded from a shared object module
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-GStreamer is extensible, so <classname>GstElements</classname> can be loaded at runtime. A plugin
+GStreamer is extensible, so <classname>GstElements</classname> can be loaded at runtime.
-system can provide one or more of the basic <application>GStreamer</application> 
+A plugin system can provide one or more of the basic <application>GStreamer</application>
 #GstPluginFeature subclasses.
 </para>
 <para>
-A plugin should export a symbol <symbol>plugin_desc</symbol> that is a struct of type #GstPluginDesc. 
+A plugin should export a symbol <symbol>plugin_desc</symbol> that is a struct of type #GstPluginDesc.
 the plugin loader will check the version of the core library the plugin was linked against
 and will create a new #GstPlugin. It will then call the #GstPluginInitFunc function
 that was provided in the plugin_desc.
 </para>
 <para>
-Once you have a handle to a #GstPlugin, you can add any object that subclasses #GstPluginFeature.
+Once you have a handle to a #GstPlugin (e.g. from the #GstRegistryPool), you can
+add any object that subclasses #GstPluginFeature.
 </para>
 <para>
 Use gst_plugin_find_feature() and gst_plugin_get_feature_list() to find features in a plugin.

docs/libs/gstreamer-libs-sections.txt

@@ -127,6 +127,7 @@ gst_dp_validate_packet
 <INCLUDE>libs/control/control.h</INCLUDE>
 gst_control_init
 <SUBSECTION Dynamic Parameter Manager>
+GstDParamManager
 gst_dpman_new
 gst_dpman_add_required_dparam_callback
 gst_dpman_add_required_dparam_direct
@@ -145,6 +146,7 @@ gst_dpman_set_parent
 gst_dpman_get_manager
 gst_dpman_bypass_dparam
 <SUBSECTION Dynamic Parameters>
+GstDParam
 gst_dparam_new
 gst_dparam_attach
 gst_dparam_detach

docs/libs/tmpl/gstcontrol.sgml

@@ -42,6 +42,20 @@ The next step is to get hold of the GstDParamManager instance of a GstElement.
 @argv: 
 
 
+<!-- ##### STRUCT GstDParamManager ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SIGNAL GstDParamManager::new-required-dparam ##### -->
+<para>
+
+</para>
+
+@gstdparammanager: the object which received the signal.
+@arg1: 
+
 <!-- ##### FUNCTION gst_dpman_new ##### -->
 <para>
 
@@ -220,6 +234,39 @@ The next step is to get hold of the GstDParamManager instance of a GstElement.
 @dparam_name: 
 
 
+<!-- ##### STRUCT GstDParam ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SIGNAL GstDParam::value-changed ##### -->
+<para>
+
+</para>
+
+@gstdparam: the object which received the signal.
+
+<!-- ##### ARG GstDParam:value-double ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GstDParam:value-float ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GstDParam:value-int ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GstDParam:value-int64 ##### -->
+<para>
+
+</para>
+
 <!-- ##### FUNCTION gst_dparam_new ##### -->
 <para>
 

docs/manual/basics-plugins.xml

@@ -66,12 +66,13 @@ struct _GstPlugin {
 
   <para> 
     You can query a <classname>GList</classname> of available plugins with the
-    function <function>gst_plugin_get_list</function> as this example shows:
+    function <function>gst_registry_pool_plugin_list</function> as this example
+    shows:
   </para> 
   <programlisting>
     GList *plugins;
     
-    plugins = gst_plugin_get_list ();
+    plugins = gst_registry_pool_plugin_list ();
 
     while (plugins) {
       GstPlugin *plugin = (GstPlugin *)plugins-&gt;data;

docs/random/ensonic/dparams.txt

@@ -18,4 +18,10 @@ $Id$
   * state of unitconvert
   * state of sychronous params
 
-* concept for global, voice params
+* dparams ng
+  * concept for global, voice params
+    one plugin instance can repeate the processing for the same input, but with
+    different parameter sets (sound synthesizers, effects)
+  * based on gobject params, so that e.g. the GUI can connect to "notify:param"
+    events and update the GUI
+

gst/gstbuffer.h

@@ -84,7 +84,8 @@ extern GType _gst_buffer_type;
  * @GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be
  * decoded independently of other buffers.
  * This flag has been deprecated, see #GST_BUFFER_DELTA_UNIT.
- * @GST_BUFFER_DONTKEEP:
+ * @GST_BUFFER_DONTKEEP: the buffer should not be ref()ed, but copied instead
+ * before doing anything with it (for specially allocated hw buffers and such)
  * @GST_BUFFER_IN_CAPS: the buffer has been added as a field in a #GstCaps.
  * @GST_BUFFER_DELTA_UNIT: this unit cannot be decoded independently.
  * Since 0.8.5
@@ -98,7 +99,7 @@ typedef enum {
   GST_BUFFER_ORIGINAL,
   GST_BUFFER_DONTFREE,
   GST_BUFFER_KEY_UNIT,		/* deprecated, use reverse DELTA_UNIT */
-  GST_BUFFER_DONTKEEP,
+  GST_BUFFER_DONTKEEP,    /* FIXME: is this deprecated ? there is no reference in gstreamer, gst-plugins */
   GST_BUFFER_IN_CAPS,
   GST_BUFFER_DELTA_UNIT,	/* this unit depends on a previous unit */
   GST_BUFFER_FLAG_LAST	= GST_DATA_FLAG_LAST + 8

gst/gsttag.h

@@ -226,39 +226,209 @@ GstTagList *	gst_event_tag_get_list		(GstEvent *		tag_event);
 
 
 /* GStreamer core tags (need to be discussed) */
+/**
+ * GST_TAG_TITLE:
+ *
+ * commonly used title
+ */
 #define GST_TAG_TITLE			"title"
+/**
+ * GST_TAG_ARTIST:
+ *
+ * person(s) responsible for the recording
+ */
 #define GST_TAG_ARTIST			"artist"
+/**
+ * GST_TAG_ALBUM:
+ *
+ * album containing this data
+ */
 #define GST_TAG_ALBUM			"album"
+/**
+ * GST_TAG_DATE:
+ *
+ * date the data was created (in Julian calendar days)
+ */
 #define GST_TAG_DATE			"date"
+/**
+ * GST_TAG_GENRE:
+ *
+ * genre this data belongs to
+ */
 #define GST_TAG_GENRE			"genre"
+/**
+ * GST_TAG_COMMENT:
+ *
+ * free text commenting the data
+ */
 #define GST_TAG_COMMENT			"comment"
+/**
+ * GST_TAG_TRACK_NUMBER:
+ *
+ * track number inside a collection
+ */
 #define GST_TAG_TRACK_NUMBER		"track-number"
+/**
+ * GST_TAG_TRACK_COUNT:
+ *
+ * count of tracks inside collection this track belongs to
+ */
 #define GST_TAG_TRACK_COUNT		"track-count"
+/**
+ * GST_TAG_ALBUM_VOLUME_NUMBER:
+ *
+ * disc number inside a collection
+ */
 #define GST_TAG_ALBUM_VOLUME_NUMBER	"album-disc-number"
+/**
+ * GST_TAG_ALBUM_VOLUME_COUNT:
+ *
+ * count of discs inside collection this disc belongs to
+ */
 #define GST_TAG_ALBUM_VOLUME_COUNT	"album-disc-count"
+/**
+ * GST_TAG_LOCATION:
+ *
+ * original location of file as a URI
+ */
 #define GST_TAG_LOCATION		"location"
+/**
+ * GST_TAG_DESCRIPTION:
+ *
+ * short text describing the content of the data
+ */
 #define GST_TAG_DESCRIPTION		"description"
+/**
+ * GST_TAG_VERSION:
+ *
+ * version of this data
+ */
 #define GST_TAG_VERSION			"version"
+/**
+ * GST_TAG_ISRC:
+ *
+ * International Standard Recording Code - see http://www.ifpi.org/isrc/
+ */
 #define GST_TAG_ISRC			"isrc"
+/**
+ * GST_TAG_ORGANIZATION:
+ *
+ * organization
+ */
 #define GST_TAG_ORGANIZATION		"organization"
+/**
+ * GST_TAG_COPYRIGHT:
+ *
+ * copyright notice of the data
+ */
 #define GST_TAG_COPYRIGHT		"copyright"
+/**
+ * GST_TAG_CONTACT:
+ *
+ * contact information
+ */
 #define GST_TAG_CONTACT			"contact"
+/**
+ * GST_TAG_LICENSE:
+ *
+ * license of data
+ */
 #define GST_TAG_LICENSE			"license"
+/**
+ * GST_TAG_PERFORMER:
+ *
+ * person(s) performing
+ */
 #define GST_TAG_PERFORMER		"performer"
+/**
+ * GST_TAG_DURATION:
+ *
+ * length in GStreamer time units (nanoseconds)
+ */
 #define GST_TAG_DURATION		"duration"
+/**
+ * GST_TAG_CODEC:
+ *
+ * codec the data is stored in
+ */
 #define GST_TAG_CODEC			"codec"
+/**
+ * GST_TAG_VIDEO_CODEC:
+ *
+ * codec the video data is stored in
+ */
 #define GST_TAG_VIDEO_CODEC		"video-codec"
+/**
+ * GST_TAG_AUDIO_CODEC:
+ *
+ * codec the audio data is stored in
+ */
 #define GST_TAG_AUDIO_CODEC		"audio-codec"
+/**
+ * GST_TAG_BITRATE:
+ *
+ * exact or average bitrate in bits/s
+ */
 #define GST_TAG_BITRATE			"bitrate"
+/**
+ * GST_TAG_NOMINAL_BITRATE:
+ *
+ * nominal bitrate in bits/s
+ */
 #define GST_TAG_NOMINAL_BITRATE		"nominal-bitrate"
+/**
+ * GST_TAG_MINIMUM_BITRATE:
+ *
+ * minimum bitrate in bits/s
+ */
 #define GST_TAG_MINIMUM_BITRATE		"minimum-bitrate"
+/**
+ * GST_TAG_MAXIMUM_BITRATE:
+ *
+ * maximum bitrate in bits/s
+ */
 #define GST_TAG_MAXIMUM_BITRATE		"maximum-bitrate"
+/**
+ * GST_TAG_SERIAL:
+ *
+ * serial number of track
+ */
 #define GST_TAG_SERIAL			"serial"
+/**
+ * GST_TAG_ENCODER:
+ *
+ * encoder used to encode this stream
+ */
 #define GST_TAG_ENCODER			"encoder"
+/**
+ * GST_TAG_ENCODER_VERSION:
+ *
+ * version of the encoder used to encode this stream
+ */
 #define GST_TAG_ENCODER_VERSION		"encoder-version"
+/**
+ * GST_TAG_TRACK_GAIN:
+ *
+ * track gain in db
+ */
 #define GST_TAG_TRACK_GAIN		"replaygain-track-gain"
+/**
+ * GST_TAG_TRACK_PEAK:
+ *
+ * peak of the track
+ */
 #define GST_TAG_TRACK_PEAK		"replaygain-track-peak"
+/**
+ * GST_TAG_ALBUM_GAIN:
+ *
+ * album gain in db
+ */
 #define GST_TAG_ALBUM_GAIN  		"replaygain-album-gain"
+/**
+ * GST_TAG_ALBUM_PEAK:
+ *
+ * peak of the album
+ */
 #define GST_TAG_ALBUM_PEAK		"replaygain-album-peak"
 
 G_END_DECLS

gst/gsttaglist.h

@@ -226,39 +226,209 @@ GstTagList *	gst_event_tag_get_list		(GstEvent *		tag_event);
 
 
 /* GStreamer core tags (need to be discussed) */
+/**
+ * GST_TAG_TITLE:
+ *
+ * commonly used title
+ */
 #define GST_TAG_TITLE			"title"
+/**
+ * GST_TAG_ARTIST:
+ *
+ * person(s) responsible for the recording
+ */
 #define GST_TAG_ARTIST			"artist"
+/**
+ * GST_TAG_ALBUM:
+ *
+ * album containing this data
+ */
 #define GST_TAG_ALBUM			"album"
+/**
+ * GST_TAG_DATE:
+ *
+ * date the data was created (in Julian calendar days)
+ */
 #define GST_TAG_DATE			"date"
+/**
+ * GST_TAG_GENRE:
+ *
+ * genre this data belongs to
+ */
 #define GST_TAG_GENRE			"genre"
+/**
+ * GST_TAG_COMMENT:
+ *
+ * free text commenting the data
+ */
 #define GST_TAG_COMMENT			"comment"
+/**
+ * GST_TAG_TRACK_NUMBER:
+ *
+ * track number inside a collection
+ */
 #define GST_TAG_TRACK_NUMBER		"track-number"
+/**
+ * GST_TAG_TRACK_COUNT:
+ *
+ * count of tracks inside collection this track belongs to
+ */
 #define GST_TAG_TRACK_COUNT		"track-count"
+/**
+ * GST_TAG_ALBUM_VOLUME_NUMBER:
+ *
+ * disc number inside a collection
+ */
 #define GST_TAG_ALBUM_VOLUME_NUMBER	"album-disc-number"
+/**
+ * GST_TAG_ALBUM_VOLUME_COUNT:
+ *
+ * count of discs inside collection this disc belongs to
+ */
 #define GST_TAG_ALBUM_VOLUME_COUNT	"album-disc-count"
+/**
+ * GST_TAG_LOCATION:
+ *
+ * original location of file as a URI
+ */
 #define GST_TAG_LOCATION		"location"
+/**
+ * GST_TAG_DESCRIPTION:
+ *
+ * short text describing the content of the data
+ */
 #define GST_TAG_DESCRIPTION		"description"
+/**
+ * GST_TAG_VERSION:
+ *
+ * version of this data
+ */
 #define GST_TAG_VERSION			"version"
+/**
+ * GST_TAG_ISRC:
+ *
+ * International Standard Recording Code - see http://www.ifpi.org/isrc/
+ */
 #define GST_TAG_ISRC			"isrc"
+/**
+ * GST_TAG_ORGANIZATION:
+ *
+ * organization
+ */
 #define GST_TAG_ORGANIZATION		"organization"
+/**
+ * GST_TAG_COPYRIGHT:
+ *
+ * copyright notice of the data
+ */
 #define GST_TAG_COPYRIGHT		"copyright"
+/**
+ * GST_TAG_CONTACT:
+ *
+ * contact information
+ */
 #define GST_TAG_CONTACT			"contact"
+/**
+ * GST_TAG_LICENSE:
+ *
+ * license of data
+ */
 #define GST_TAG_LICENSE			"license"
+/**
+ * GST_TAG_PERFORMER:
+ *
+ * person(s) performing
+ */
 #define GST_TAG_PERFORMER		"performer"
+/**
+ * GST_TAG_DURATION:
+ *
+ * length in GStreamer time units (nanoseconds)
+ */
 #define GST_TAG_DURATION		"duration"
+/**
+ * GST_TAG_CODEC:
+ *
+ * codec the data is stored in
+ */
 #define GST_TAG_CODEC			"codec"
+/**
+ * GST_TAG_VIDEO_CODEC:
+ *
+ * codec the video data is stored in
+ */
 #define GST_TAG_VIDEO_CODEC		"video-codec"
+/**
+ * GST_TAG_AUDIO_CODEC:
+ *
+ * codec the audio data is stored in
+ */
 #define GST_TAG_AUDIO_CODEC		"audio-codec"
+/**
+ * GST_TAG_BITRATE:
+ *
+ * exact or average bitrate in bits/s
+ */
 #define GST_TAG_BITRATE			"bitrate"
+/**
+ * GST_TAG_NOMINAL_BITRATE:
+ *
+ * nominal bitrate in bits/s
+ */
 #define GST_TAG_NOMINAL_BITRATE		"nominal-bitrate"
+/**
+ * GST_TAG_MINIMUM_BITRATE:
+ *
+ * minimum bitrate in bits/s
+ */
 #define GST_TAG_MINIMUM_BITRATE		"minimum-bitrate"
+/**
+ * GST_TAG_MAXIMUM_BITRATE:
+ *
+ * maximum bitrate in bits/s
+ */
 #define GST_TAG_MAXIMUM_BITRATE		"maximum-bitrate"
+/**
+ * GST_TAG_SERIAL:
+ *
+ * serial number of track
+ */
 #define GST_TAG_SERIAL			"serial"
+/**
+ * GST_TAG_ENCODER:
+ *
+ * encoder used to encode this stream
+ */
 #define GST_TAG_ENCODER			"encoder"
+/**
+ * GST_TAG_ENCODER_VERSION:
+ *
+ * version of the encoder used to encode this stream
+ */
 #define GST_TAG_ENCODER_VERSION		"encoder-version"
+/**
+ * GST_TAG_TRACK_GAIN:
+ *
+ * track gain in db
+ */
 #define GST_TAG_TRACK_GAIN		"replaygain-track-gain"
+/**
+ * GST_TAG_TRACK_PEAK:
+ *
+ * peak of the track
+ */
 #define GST_TAG_TRACK_PEAK		"replaygain-track-peak"
+/**
+ * GST_TAG_ALBUM_GAIN:
+ *
+ * album gain in db
+ */
 #define GST_TAG_ALBUM_GAIN  		"replaygain-album-gain"
+/**
+ * GST_TAG_ALBUM_PEAK:
+ *
+ * peak of the album
+ */
 #define GST_TAG_ALBUM_PEAK		"replaygain-album-peak"
 
 G_END_DECLS

gst/gstvalue.c

@@ -2037,7 +2037,7 @@ gst_value_register_union_func (GType type1, GType type2, GstValueUnionFunc func)
  * type, or if there is a method (registered by
  * #gst_value_register_intersection_func) to calculate the intersection.
  *
- * Returns:
+ * Returns: TRUE if the values can intersect
  */
 gboolean
 gst_value_can_intersect (const GValue * value1, const GValue * value2)