[babl] introspection: Add GI/GTKDoc style symbol references to comments

[Jon Nordby <jonnor src gnome org>]

commit 1b254185cc14bd7019232f8b47ccd43bfe7f1497
Author: Jon Nordby <jononor gmail com>
Date:   Tue Jul 31 18:19:02 2012 +0200

    introspection: Add GI/GTKDoc style symbol references to comments

 babl/babl.h |   64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 61 insertions(+), 3 deletions(-)
---
diff --git a/babl/babl.h b/babl/babl.h
index c1c5e9d..546fad6 100644
--- a/babl/babl.h
+++ b/babl/babl.h
@@ -31,23 +31,31 @@ extern "C" {
 
 
 /**
+ * babl_init:
+ *
  * Initializes the babl library.
  */
 void         babl_init      (void);
 
 /**
+ * babl_exit:
+ *
  * Deinitializes the babl library and frees any resources used when
  * matched with the number of calls to babl_init().
  */
 void         babl_exit      (void);
 
 /**
+ * babl_type:
+ *
  * Returns the babl object representing the data type given by @name
  * such as for example "u8", "u16" or "float".
  */
 const Babl * babl_type      (const char *name);
 
 /**
+ * babl_sampling:
+ *
  * Returns the babl object representing the @horizontal and @vertical
  * sampling such as for example 2, 2 for the chroma components in
  * YCbCr.
@@ -56,31 +64,43 @@ const Babl * babl_sampling  (int horizontal,
                              int vertical);
 
 /**
+ * babl_component:
+ *
  * Returns the babl object representing the color component given by
  * @name such as for example "R", "cyan" or "CIE L".
  */
 const Babl * babl_component (const char *name);
 
 /**
+ * babl_model:
+ *
  * Returns the babl object representing the color model given by @name
  * such as for example "RGB", "CMYK" or "CIE Lab".
  */
 const Babl * babl_model     (const char *name);
 
 /**
+ * babl_format:
+ *
  * Returns the babl object representing the color format given by
  * @name such as for example "RGB u8", "CMYK float" or "CIE Lab u16".
  */
 const Babl * babl_format    (const char *name);
 
-/*  Create a babl fish capable of converting from source_format to
+/**
+ * babl_fish:
+ *
+ *  Create a babl fish capable of converting from source_format to
  *  destination_format, source and destination can be either strings
  *  with the names of the formats or Babl-format objects.
  */
 const Babl * babl_fish      (const void *source_format,
                              const void *destination_format);
 
-/** Process n pixels from source to destination using babl_fish,
+/**
+ * babl_process:
+ *
+ *  Process n pixels from source to destination using babl_fish,
  *  returns number of pixels converted.
  */
 long         babl_process   (const Babl *babl_fish,
@@ -90,31 +110,43 @@ long         babl_process   (const Babl *babl_fish,
 
 
 /**
+ * babl_get_name:
+ *
  * Returns a string decsribing a Babl object.
  */
 const char * babl_get_name                     (const Babl *babl);
 
 /**
+ * babl_format_has_alpha:
+ *
  * Returns whether the @format has an alpha channel.
  */
 int          babl_format_has_alpha             (const Babl *format);
 
 /**
+ * babl_format_get_bytes_per_pixel:
+ *
  * Returns the bytes per pixel for a babl color format.
  */
 int          babl_format_get_bytes_per_pixel   (const Babl *format);
 
 /**
+ * babl_format_get_model:
+ *
  * Return the model used for constructing the format.
  */
 const Babl * babl_format_get_model             (const Babl *format);
 
 /**
+ * babl_format_get_n_components:
+ *
  * Returns the number of components for the given @format.
  */
 int          babl_format_get_n_components      (const Babl *format);
 
 /**
+ * babl_format_get_type:
+ *
  * Returns the type in the given @format for the given
  * @component_index.
  */
@@ -123,6 +155,8 @@ const Babl * babl_format_get_type              (const Babl *format,
 
 
 /**
+ * babl_type_new:
+ *
  * Defines a new data type in babl. A data type that babl can have in
  * its buffers requires conversions to and from "double" to be
  * registered before passing sanity.
@@ -137,6 +171,8 @@ const Babl * babl_type_new (void *first_arg,
                             ...) BABL_ARG_NULL_TERMINATED;
 
 /**
+ * babl_component_new:
+ *
  * Defines a new color component with babl.
  *
  *     babl_component_new  (const char *name,
@@ -146,6 +182,8 @@ const Babl * babl_component_new  (void *first_arg,
                                   ...) BABL_ARG_NULL_TERMINATED;
 
 /**
+ * babl_model_new:
+ *
  * Defines a new color model in babl. If no name is provided a name is
  * generated by concatenating the name of all the involved components.
  *
@@ -158,6 +196,8 @@ const Babl * babl_model_new (void *first_arg,
                             ...) BABL_ARG_NULL_TERMINATED;
 
 /**
+ * babl_format_new:
+ *
  * Defines a new pixel format in babl. Provided BablType and|or
  * BablSampling is valid for the following components as well. If no
  * name is provided a (long) descriptive name is used.
@@ -178,6 +218,8 @@ const Babl * babl_format_new (const void *first_arg,
                               ...) BABL_ARG_NULL_TERMINATED;
 
 /*
+ * babl_format_n:
+ *
  * Defines a new pixel format in babl. With the specified data storage
  * type and the given number of components. At the moment behavior of
  * conversions are only well defined to other babl_format_n derived formats
@@ -188,11 +230,15 @@ babl_format_n (const Babl *type,
                int   components);
 
 /**
+ * babl_format_is_format_n:
+ *
  * Returns whether the @format is a format_n type.
  */
 int babl_format_is_format_n (const Babl *format);
 
 /**
+ * babl_conversion_new:
+ *
  * Defines a new conversion between either two formats, two models or
  * two types in babl.
  *
@@ -207,6 +253,8 @@ const Babl * babl_conversion_new (const void *first_arg,
 
 
 /**
+ * babl_new_palette:
+ *
  * create a new palette based format, name is optional pass in NULL to get
  * an anonymous format. If you pass in with_alpha the format also gets
  * an 8bit alpha channel. Returns the BablModel of the color model. If
@@ -218,11 +266,15 @@ const Babl *babl_new_palette (const char  *name,
                               const Babl **format_u8_with_alpha);
 
 /**
+ * babl_format_is_palette:
+ *
  * check whether a format is a palette backed format.
  */
 int   babl_format_is_palette   (const Babl *format);
 
 /**
+ * babl_palette_set_palette:
+ *
  * Assign a palette to a palette format, the data is a single span of pixels
  * representing the colors of the palette.
  */
@@ -232,6 +284,8 @@ void  babl_palette_set_palette (const Babl        *babl,
                                 int                count);
 
 /**
+ * babl_palette_reset:
+ *
  * reset a palette to initial state, frees up some caches that optimize
  * conversions.
  */
@@ -240,6 +294,8 @@ void  babl_palette_reset       (const Babl        *babl);
 
 
 /**
+ * babl_set_user_data: (skip)
+ *
  * associate a data pointer with a format/model, this data can be accessed and
  * used from the conversion functions, encoding color profiles, palettes or
  * similar with the data, perhaps this should be made internal API, not
@@ -248,7 +304,9 @@ void  babl_palette_reset       (const Babl        *babl);
 void   babl_set_user_data     (const Babl *babl, void *data);
 
 /**
- * get data set with babl_set_user_data
+ * babl_get_user_data: (skip)
+ *
+ * Get data set with babl_set_user_data
  */
 void * babl_get_user_data     (const Babl *babl);