libgimp/gimpchannel.c libgimp/gimpimage.c libgimp/gimplayer.c

2000-08-25  Sven Neumann  <sven@gimp.org>

        * libgimp/gimpchannel.c
        * libgimp/gimpimage.c
        * libgimp/gimplayer.c
        * libgimp/gimpproceduraldb.c
        * libgimp/gimpselection.c: document wrapped PDB wrappers

ChangeLog

@@ -1,3 +1,11 @@
+2000-08-25  Sven Neumann  <sven@gimp.org>
+
+	* libgimp/gimpchannel.c
+	* libgimp/gimpimage.c
+	* libgimp/gimplayer.c
+	* libgimp/gimpproceduraldb.c
+	* libgimp/gimpselection.c: document wrapped PDB wrappers
+
 2000-08-25  Sven Neumann  <sven@gimp.org>
 
 	* libgimp/gimp*_pdb.c

libgimp/gimpchannel.c

@@ -22,6 +22,27 @@
 #include "gimp.h"
 
 
+/**
+ * gimp_channel_new:
+ * @image_ID: The image to which to add the channel.
+ * @name: The channel name.
+ * @width: The channel width.
+ * @height: The channel height.
+ * @opacity: The channel opacity.
+ * @color: The channel compositing color.
+ *
+ * Create a new channel.
+ *
+ * This procedure creates a new channel with the specified width and
+ * height. Name, opacity, and color are also supplied parameters. The
+ * new channel still needs to be added to the image, as this is not
+ * automatic. Add the new channel with the 'gimp_image_add_channel'
+ * command. Other attributes such as channel show masked, should be set
+ * with explicit procedure calls. The channel's contents are undefined
+ * initially.
+ *
+ * Returns: The newly created channel.
+ */
 gint32
 gimp_channel_new (gint32   image_ID,
 		  gchar   *name,

libgimp/gimpimage.c

@@ -22,6 +22,19 @@
 #include "gimp.h"
 
 
+/**
+ * gimp_image_get_cmap:
+ * @image_ID: The image.
+ * @num_colors: Number of colors in the colormap array.
+ *
+ * Returns the image's colormap
+ *
+ * This procedure returns an actual pointer to the image's colormap, as
+ * well as the number of colors contained in the colormap. If the image 
+ * is not of base type INDEXED, this pointer will be NULL.
+ *
+ * Returns: The image's colormap.
+ */
 guchar *
 gimp_image_get_cmap (gint32  image_ID,
 		     gint   *num_colors)
@@ -37,6 +50,21 @@ gimp_image_get_cmap (gint32  image_ID,
   return cmap;
 }
 
+/**
+ * gimp_image_set_cmap:
+ * @image_ID: The image.
+ * @cmap: The new colormap values.
+ * @num_colors: Number of colors in the colormap array.
+ *
+ * Sets the entries in the image's colormap.
+ *
+ * This procedure sets the entries in the specified image's colormap.
+ * The number of colors is specified by the \"num_colors\" parameter
+ * and corresponds to the number of INT8 triples that must be contained
+ * in the \"cmap\" array.
+ *
+ * Returns: TRUE on success.
+ */
 gboolean
 gimp_image_set_cmap (gint32  image_ID,
 		     guchar *cmap,

libgimp/gimplayer.c

@@ -21,6 +21,27 @@
 
 #include "gimp.h"
 
+/**
+ * gimp_layer_new:
+ * @image_ID: The image to which to add the layer.
+ * @name: The layer name.
+ * @width: The layer width.
+ * @height: The layer height.
+ * @type: The layer type.
+ * @opacity: The layer opacity.
+ * @mode: The layer combination mode.
+ *
+ * Create a new layer.
+ *
+ * This procedure creates a new layer with the specified width, height,
+ * and type. Name, opacity, and mode are also supplied parameters. The
+ * new layer still needs to be added to the image, as this is not
+ * automatic. Add the new layer with the 'gimp_image_add_layer'
+ * command. Other attributes such as layer mask modes, and offsets
+ * should be set with explicit procedure calls.
+ *
+ * Returns: The newly created layer.
+ */
 gint32
 gimp_layer_new (gint32                image_ID,
 		gchar                *name,
@@ -39,6 +60,20 @@ gimp_layer_new (gint32                image_ID,
 			  mode);
 }
 
+/**
+ * gimp_layer_copy:
+ * @layer_ID: The layer to copy.
+ *
+ * Copy a layer.
+ *
+ * This procedure copies the specified layer and returns the copy. The
+ * newly copied layer is for use within the original layer's image. It
+ * should not be subsequently added to any other image. If you create
+ * a copy of the background layer, remember to add an alpha channel
+ * before you add the new layer to the image.
+ *
+ * Returns: The newly copied layer.
+ */
 gint32
 gimp_layer_copy (gint32  layer_ID)
 {

libgimp/gimpproceduraldb.c

@@ -21,6 +21,31 @@
 
 #include "gimp.h"
 
+/**
+ * gimp_procedural_db_proc_info:
+ * @procedure: The procedure name.
+ * @blurb: A short blurb.
+ * @help: Detailed procedure help.
+ * @author: Author(s) of the procedure.
+ * @copyright: The copyright.
+ * @date: Copyright date.
+ * @proc_type: The procedure type.
+ * @num_args: The number of input arguments.
+ * @num_values: The number of return values.
+ * @args: The input arguments.
+ * @return_vals: The return values.
+ *
+ * Queries the procedural database for information on the specified
+ * procedure.
+ *
+ * This procedure returns information on the specified procedure. A
+ * short blurb, detailed help, author(s), copyright information,
+ * procedure type, number of input, and number of return values are 
+ * returned. Additionally this function returns specific information 
+ * about each input argument and return value.
+ *
+ * Returns: TRUE on success.
+ */
 gboolean
 gimp_procedural_db_proc_info (gchar            *procedure,
 			      gchar           **blurb,
@@ -86,6 +111,20 @@ gimp_procedural_db_proc_info (gchar            *procedure,
   return success;
 }
 
+/**
+ * gimp_procedural_db_get_data:
+ * @identifier: The identifier associated with data.
+ * @data: A byte array containing data.
+ *
+ * Returns data associated with the specified identifier.
+ *
+ * This procedure returns any data which may have been associated with
+ * the specified identifier. The data is copied into the given memory 
+ * location.
+ *
+ * Returns: TRUE on success, FALSE if no data has been associated with 
+ * the identifier
+ */
 gboolean
 gimp_procedural_db_get_data (gchar    *identifier,
 			     gpointer  data)
@@ -106,6 +145,19 @@ gimp_procedural_db_get_data (gchar    *identifier,
   return success;
 }
 
+/**
+ * gimp_procedural_db_set_data:
+ * @identifier: The identifier associated with data.
+ * @data: A byte array containing data.
+ *
+ * Associates the specified identifier with the supplied data.
+ *
+ * This procedure associates the supplied data with the provided
+ * identifier. The data may be subsequently retrieved by a call to
+ * 'procedural-db-get-data'.
+ *
+ * Returns: TRUE on success.
+ */
 gboolean
 gimp_procedural_db_set_data (gchar    *identifier,
 			     gpointer  data,

libgimp/gimpselection.c

@@ -21,6 +21,24 @@
 
 #include "gimp.h"
 
+/**
+ * gimp_selection_float:
+ * @image_ID: ignored
+ * @drawable_ID: The drawable from which to float selection.
+ * @offx: x offset for translation.
+ * @offy: y offset for translation.
+ *
+ * Float the selection from the specified drawable with initial offsets
+ * as specified.
+ *
+ * This procedure determines the region of the specified drawable that
+ * lies beneath the current selection. The region is then cut from the
+ * drawable and the resulting data is made into a new layer which is
+ * instantiated as a floating selection. The offsets allow initial
+ * positioning of the new floating selection.
+ *
+ * Returns: The floated layer.
+ */
 gint32
 gimp_selection_float (gint32 image_ID,
 		      gint32 drawable_ID,
@@ -31,4 +49,3 @@ gimp_selection_float (gint32 image_ID,
 				offx, 
 				offy);
 }
-