more docs and two more inlined

Original commit message from CVS:
* docs/gst/tmpl/.cvsignore:
* docs/gst/tmpl/gstformat.sgml:
* docs/gst/tmpl/gstversion.sgml:
* gst/gstbus.h:
* gst/gstformat.c:
* gst/gstformat.h:
* gst/gstversion.h.in:
more docs and two more inlined

4 files changed, 69 insertions, 7 deletions

diff --git a/gst/gstbus.h b/gst/gstbus.h
index f57430d70..54eb2c6a8 100644
--- a/gst/gstbus.h
+++ b/gst/gstbus.h
@@ -71,7 +71,8 @@ typedef GstBusSyncReply (*GstBusSyncHandler) 	(GstBus * bus, GstMessage * messag
  * @data: user data that has been given, when registering the handler
  *
  * Handler will be invoked asynchronously, after a new message has been injected
- * into the bus.
+ * into the bus. Return %TRUE if the message has been handled. It will then be
+ * taken from the bus and _unref()'ed.
  *
  * Returns: %TRUE if message should be taken from the bus
  */
diff --git a/gst/gstformat.c b/gst/gstformat.c
index 975be2523..2ffb77b9f 100644
--- a/gst/gstformat.c
+++ b/gst/gstformat.c
@@ -20,6 +20,14 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION:gstformat
+ * @short_description: Dynamically register new data formats
+ * @see_also: #GstPad, #GstElement
+ *
+ * GstFormats functions are used to register a new format to the gstreamer core.
+ * Formats can be used to perform seeking or conversions/query operations.
+ */
 
 #include <string.h>
 
diff --git a/gst/gstformat.h b/gst/gstformat.h
index 909f9d9c4..f38f3d46b 100644
--- a/gst/gstformat.h
+++ b/gst/gstformat.h
@@ -31,6 +31,17 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GstFormat:
+ * @GST_FORMAT_UNDEFINED: undefined format
+ * @GST_FORMAT_DEFAULT: the default format of the pad/element
+ * @GST_FORMAT_BYTES: bytes
+ * @GST_FORMAT_TIME: time in nanoseconds
+ * @GST_FORMAT_BUFFERS: buffers
+ * @GST_FORMAT_PERCENT: percentage of stream
+ *
+ * Standard predefined formats
+ */
 typedef enum {
   GST_FORMAT_UNDEFINED 	=  0, /* must be first in list */
   GST_FORMAT_DEFAULT   	=  1, /* samples for audio, frames/fields for video */
@@ -41,11 +52,30 @@ typedef enum {
 } GstFormat;
 
 /* a percentage is always relative to 1000000 */
+/**
+ * GST_FORMAT_PERCENT_MAX:
+ *
+ * The PERCENT format is between 0 and this value
+ */
 #define	GST_FORMAT_PERCENT_MAX		G_GINT64_CONSTANT (1000000)
+/**
+ * GST_FORMAT_PERCENT_SCALE:
+ *
+ * The value used to scale down the reported PERCENT format value to
+ * its real value.
+ */
 #define	GST_FORMAT_PERCENT_SCALE	G_GINT64_CONSTANT (10000)
 
 typedef struct _GstFormatDefinition GstFormatDefinition;
 
+/**
+ * GstFormatDefinition:
+ * @value: The unique id of this format
+ * @nick: A short nick of the format
+ * @description: A longer description of the format
+ *
+ * A format definition
+ */
 struct _GstFormatDefinition 
 {
   GstFormat  value;
diff --git a/gst/gstversion.h.in b/gst/gstversion.h.in
index 048a2c389..54240734c 100644
--- a/gst/gstversion.h.in
+++ b/gst/gstversion.h.in
@@ -19,21 +19,44 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
-
+/**
+ * SECTION:gstversion
+ * @short_description: GStreamer version macros.
+ *
+ * Use the GST_VERSION_* macros e.g. when defining own plugins. The GStreamer
+ * runtime checks if these plugin and core version match and refuses to use a
+ * plugin compiled against a different version of GStreamer.
+ * You can also use the macros to keep the GStreamer version information in your
+ * application.
+ *
+ * Use the gst_version() function if you want to know which version of 
+ * GStreamer you are currently linked against.
+ *
+ * The version macros get defined by including "gst/gst.h".
+ */
 
 #ifndef __GST_VERSION_H__
 #define __GST_VERSION_H__
 
 G_BEGIN_DECLS
 
-/*
- * Use these only when you want to know what GStreamer version your stuff was
- * compiled against.
- * Use the #gst_version function if you want to know which version of 
- * GStreamer you are currently linked against.
+/**
+ * GST_VERSION_MAJOR:
+ *
+ * The major version of GStreamer at compile time:
  */
 #define GST_VERSION_MAJOR (@GST_VERSION_MAJOR@)
+/**
+ * GST_VERSION_MINOR:
+ *
+ * The minor version of GStreamer at compile time:
+ */
 #define GST_VERSION_MINOR (@GST_VERSION_MINOR@)
+/**
+ * GST_VERSION_MICRO:
+ *
+ * The micro version of GStreamer at compile time:
+ */
 #define GST_VERSION_MICRO (@GST_VERSION_MICRO@)
 
 void    gst_version     (guint *major, guint *minor, guint *micro);