GNOME.org
 

[gimp/osx-build: 52/55] Add API-documentation, fixes

commit 0657a68d2ef18f9f8c67e9fad938406b1ff6f38f
Author: Sven Claussner <sclaussner src gnome org>
Date:   Thu Jul 17 21:00:21 2014 +0200

    Add API-documentation, fixes
    
    Document XCF functions and a macro.
    Minor fixes

 app/xcf/xcf-load.c           |   15 +++---
 app/xcf/xcf-private.h        |  111 ++++++++++++++++++++++++++++++++++++++++++
 app/xcf/xcf-read.c           |   59 ++++++++++++++++++++++
 app/xcf/xcf-save.c           |   38 ++++++++++++++-
 app/xcf/xcf-seek.c           |   27 ++++++++++
 app/xcf/xcf-write.c          |   55 ++++++++++++++++++++-
 app/xcf/xcf.c                |   30 +++++++++++
 devel-docs/app/app-docs.sgml |    2 +-
 devel-docs/xcf.txt           |    8 +++
 9 files changed, 333 insertions(+), 12 deletions(-)
---
diff --git a/app/xcf/xcf-load.c b/app/xcf/xcf-load.c
index cb82f58..88cf6f5 100644
--- a/app/xcf/xcf-load.c
+++ b/app/xcf/xcf-load.c
@@ -75,7 +75,7 @@
  * SECTION:xcf-load
  * @Short_description:XCF file loader functions
  *
- * This section describes the XCF file loader.
+ * XCF file loader
  */
 
 #define MAX_XCF_PARASITE_DATA_LEN (256L * 1024 * 1024)
@@ -140,17 +140,16 @@ static gboolean        xcf_skip_unknown_prop  (XcfInfo      *info,
 
 /**
  * xcf_load_image:
- *
- * @gimp:  Pointer to the #Gimp instance
- * @info:  Pointer to the #XcfInfo structure of the file to open
+ * @gimp:  #Gimp instance
+ * @info:  #XcfInfo structure of the file to open
  * @error: Return location for hard errors
  *
- * Returns: Image of type #GimpImage with the loaded content from the XCF file
- *          or %NULL if a hard error occured.
+ * Loads an image from an XCF file.
  *
- * On hard errors, @error will contain the occured error and %NULL be returned.
+ * Returns: Image of type #GimpImage with the loaded content from the XCF file
+ *          or %NULL if a hard error occurred.
+ * On hard errors, @error will contain the occurred error and %NULL be returned.
  *
- * Loads an image from an XCF file.
  */
 GimpImage *
 xcf_load_image (Gimp     *gimp,
diff --git a/app/xcf/xcf-private.h b/app/xcf/xcf-private.h
index 33076d4..03a25ed 100644
--- a/app/xcf/xcf-private.h
+++ b/app/xcf/xcf-private.h
@@ -18,7 +18,64 @@
 #ifndef __XCF_PRIVATE_H__
 #define __XCF_PRIVATE_H__
 
+/**
+ * SECTION:xcf-private
+ * @Short_description:Common definitions for the XCF functions
+ *
+ * Common enum and structs definitions for the XCF functions
+ */
 
+
+/**
+* PropType:
+* @PROP_END:                 marks the end of any property list
+* @PROP_COLORMAP:            stores the color map in indexed images
+* @PROP_ACTIVE_LAYER:        marks the active layer in an image
+* @PROP_ACTIVE_CHANNEL:      marks the active channel in an image
+* @PROP_SELECTION:           marks the selection
+* @PROP_FLOATING_SELECTION:  marks the layer that is the floating selection
+* @PROP_OPACITY:             specifies the layer's or channel opacity
+* @PROP_MODE:                layer mode of the layer
+* @PROP_VISIBLE:             specifies the visibility of a layer or channel
+* @PROP_LINKED:              controls the behavior of Transform tools with
+*                            linked elements (layers, channels, paths)
+* @PROP_LOCK_ALPHA:          prevents drawing tools from increasing alpha of any
+*                            pixel in the layer
+* @PROP_APPLY_MASK:          specifies whether the layer mask shall be applied
+*                            to the layer
+* @PROP_EDIT_MASK:           specifies whether the layer mask is currently being
+*                            edited
+* @PROP_SHOW_MASK:           specifies whether the layer mask is visible
+* @PROP_SHOW_MASKED:         specifies whether a channel is shown as a mask
+* @PROP_OFFSETS:             gives the coordinates of the upper left corner of
+*                            the layer relative to the upper left corner of the
+*                            canvas
+* @PROP_COLOR:               specifies the color of the screen that is used to
+*                            represent the channel when it is visible in the UI
+* @PROP_COMPRESSION:         defines the encoding of pixels in tile data blocks
+*                            in the entire XCF file
+* @PROP_GUIDES:              stores the horizontal or vertical positions of
+*                            guides
+* @PROP_RESOLUTION:          specifies the intended physical size of the image's
+*                            pixels
+* @PROP_TATTOO:              unique identifier for the denoted image, channel or
+*                            layer
+* @PROP_PARASITES:           stores parasites
+* @PROP_UNIT:                specifies the units used to specify resolution in
+*                            the Scale Image and Print Size dialogs
+* @PROP_PATHS:               stores the paths (old method up to GIMP 1.2)
+* @PROP_USER_UNIT:           defines non-standard units
+* @PROP_VECTORS:             stores the paths (since GIMP 1.3.21)
+* @PROP_TEXT_LAYER_FLAGS:    specifies the text layer behavior
+* @PROP_SAMPLE_POINTS:       specifies the sample points
+* @PROP_LOCK_CONTENT:        specifies whether the layer, channel or path cannot
+*                            be edited
+* @PROP_GROUP_ITEM:          indicates that the layer is a layer group
+* @PROP_ITEM_PATH:           TODO describe
+* @PROP_GROUP_ITEM_FLAGS:    specifies flags for the layer group
+*
+* Enum for property types.
+*/
 typedef enum
 {
   PROP_END                =  0,
@@ -55,6 +112,15 @@ typedef enum
   PROP_GROUP_ITEM_FLAGS   = 31
 } PropType;
 
+/**
+ * XcfCompressionType:
+ * @COMPRESS_NONE:    no compression
+ * @COMPRESS_RLE:     Run-Length-Encoding
+ * @COMPRESS_ZLIB:    reserved for zlib-based compression
+ * @COMPRESS_FRACTAL: reserved for fractal compression
+ *
+ * Enum for image compression types. Currently we only use @COMPRESS_RLE
+ */
 typedef enum
 {
   COMPRESS_NONE              =  0,
@@ -63,23 +129,68 @@ typedef enum
   COMPRESS_FRACTAL           =  3   /* unused */
 } XcfCompressionType;
 
+/**
+ * XcfOrientationType:
+ * @XCF_ORIENTATION_HORIZONTAL: Horizontal guide
+ * @XCF_ORIENTATION_VERTICAL:   Vertical guide
+ *
+ * Enum for guide orientations
+ */
 typedef enum
 {
   XCF_ORIENTATION_HORIZONTAL = 1,
   XCF_ORIENTATION_VERTICAL   = 2
 } XcfOrientationType;
 
+
+/**
+ * XcfStrokeType:
+ * @XCF_STROKETYPE_STROKE:        Vector stroke is a plain stroke (??, unused)
+ * @XCF_STROKETYPE_BEZIER_STROKE: Vector stroke is a Bezier stroke.
+ *
+ * Enum for path strokes
+ */
+
+ /* TODO: verify XCF_STROKETYPE_STROKE
+ * TODO: unused - use or remove
+ */
 typedef enum
 {
   XCF_STROKETYPE_STROKE        = 0,
   XCF_STROKETYPE_BEZIER_STROKE = 1
 } XcfStrokeType;
 
+/**
+ * XcfGroupItemFlagsType:
+ * @XCF_GROUP_ITEM_EXPANDED: specfies whether the layer group is expanded.
+ *
+ * Enum for group item flags
+ */
 typedef enum
 {
   XCF_GROUP_ITEM_EXPANDED      = 1
 } XcfGroupItemFlagsType;
 
+/**
+* XcfInfo:
+* @gimp:                  #Gimp instance
+* @progress:              progress indicator
+* @fp:                    file stream of the XCF file
+* @cp:                    position in the XCF file.
+* @filename:              image filename
+* @tattoo_state:          tattoo state associated with the image
+* @active_layer:          active layer of the image
+* @active_channel:        active channel of the image
+* @floating_sel_drawable: the drawable the floating layer is attached to
+* @floating_sel:          floating selection of the image
+* @floating_sel_offset:   the floating selection's position in the XCF file
+* @swap_num:              unused (TODO: use or remove)
+* @ref_count:             unused (TODO: use or remove)
+* @compression:           file compression (see @XcfCompressionType)
+* @file_version:          file format version (see xcf_save_choose_format())
+*
+* XCF file information structure.
+*/
 typedef struct _XcfInfo  XcfInfo;
 
 struct _XcfInfo
diff --git a/app/xcf/xcf-read.c b/app/xcf/xcf-read.c
index d087c86..1d850a5 100644
--- a/app/xcf/xcf-read.c
+++ b/app/xcf/xcf-read.c
@@ -27,8 +27,36 @@
 
 #include "gimp-intl.h"
 
+/**
+ * SECTION:xcf-read
+ * @Short_description:XCF reading functions
+ *
+ * Low-level XCF reading functions
+ */
+
+/**
+ * MAX_XCF_STRING_LEN:
+<<<<<<< Upstream, based on origin/osx-build
+ *
+ * Maximum length of a string in an XCF file ((16L * 1024 * 1024) bytes)
+=======
+ * @MAX_XCF_STRING_LEN: maximum length of a string in an XCF file
+ * ((16L * 1024 * 1024) bytes)
+>>>>>>> 059857a API-doc minor fixes
+ */
 #define MAX_XCF_STRING_LEN (16L * 1024 * 1024)
 
+/**
+ * xcf_read_int32:
+ * @fp:    input file stream
+ * @data:  destination data array
+ * @count: number of words to read
+ *
+ * Read @count 4-byte-words from @fp into @data.
+ * The functions respects the machine specific byte order.
+ *
+ * Returns: number of read bytes (not words)
+ */
 guint
 xcf_read_int32 (FILE    *fp,
                 guint32 *data,
@@ -50,6 +78,16 @@ xcf_read_int32 (FILE    *fp,
   return total;
 }
 
+/**
+ * xcf_read_float:
+ * @fp:    input file stream
+ * @data:  destination data array
+ * @count: number of words to read
+ *
+ * Read @count float values from @fp into @data.
+ *
+ * Returns: number of read bytes
+ */
 guint
 xcf_read_float (FILE   *fp,
                 gfloat *data,
@@ -58,6 +96,16 @@ xcf_read_float (FILE   *fp,
   return xcf_read_int32 (fp, (guint32 *) ((void *) data), count);
 }
 
+/**
+ * xcf_read_int8:
+ * @fp:    input file stream
+ * @data:  destination data array
+ * @count: number of bytes to read
+ *
+ * Read @count bytes from @fp into @data.
+ *
+ * Returns: number of read bytes
+ */
 guint
 xcf_read_int8 (FILE   *fp,
                guint8 *data,
@@ -81,6 +129,17 @@ xcf_read_int8 (FILE   *fp,
   return total;
 }
 
+/**
+ * xcf_read_string:
+ * @fp:    input file stream
+ * @data:  destination data array
+ * @count: number of strings to read
+ *
+ * Read @count bytes from @fp into @data
+ * and convert them to UTF8.
+ *
+ * Returns: number of read bytes
+ */
 guint
 xcf_read_string (FILE   *fp,
                  gchar **data,
diff --git a/app/xcf/xcf-save.c b/app/xcf/xcf-save.c
index 627857e..f314373 100644
--- a/app/xcf/xcf-save.c
+++ b/app/xcf/xcf-save.c
@@ -68,6 +68,13 @@
 #include "gimp-intl.h"
 
 
+/**
+ * SECTION:xcf-save
+ * @Short_description:XCF file saver functions
+ *
+ * XCF file saver
+ */
+
 static gboolean xcf_save_image_props   (XcfInfo           *info,
                                         GimpImage         *image,
                                         GError           **error);
@@ -176,6 +183,23 @@ static gboolean xcf_save_vectors       (XcfInfo           *info,
 
 static const guint32 zero;
 
+/**
+ * xcf_save_choose_format:
+ * @info:  #XcfInfo structure of the file to save
+ * @image: Image to save
+ *
+ * Determines the format version for saving the image to an XCF file:
+ *
+ * 0: Nothing special is in the image.
+ *
+ * 1: Image has color map.
+ *
+ * 2: Image uses one of the layer modes "Soft light", "Grain extract",
+ *    "Grain merge" or "Color erase".
+ *
+ * 3: Image contains a layer group.
+ *
+ */
 void
 xcf_save_choose_format (XcfInfo   *info,
                         GimpImage *image)
@@ -183,7 +207,7 @@ xcf_save_choose_format (XcfInfo   *info,
   GList *list;
   gint   save_version = 0;  /* default to oldest */
 
-  /* need version 1 for colormaps */
+  /* need version 1 for color maps */
   if (gimp_image_get_colormap (image))
     save_version = 1;
 
@@ -215,6 +239,16 @@ xcf_save_choose_format (XcfInfo   *info,
   info->file_version = save_version;
 }
 
+/**
+ * xcf_save_image:
+ * @info:  #XcfInfo structure of the file to save
+ * @image: Image to save
+ * @error: Return location for errors
+ *
+ * Saves the image to an XCF file.
+ *
+ * Returns: 0 if file errors occurred
+ */
 gint
 xcf_save_image (XcfInfo    *info,
                 GimpImage  *image,
@@ -344,7 +378,7 @@ xcf_save_image_props (XcfInfo    *info,
 
   gimp_image_get_resolution (image, &xres, &yres);
 
-  /* check and see if we should save the colormap property */
+  /* check and see if we should save the color map property */
   if (gimp_image_get_colormap (image))
     xcf_check_error (xcf_save_prop (info, image, PROP_COLORMAP, error,
                                     gimp_image_get_colormap_size (image),
diff --git a/app/xcf/xcf-seek.c b/app/xcf/xcf-seek.c
index e75eb57..3821197 100644
--- a/app/xcf/xcf-seek.c
+++ b/app/xcf/xcf-seek.c
@@ -29,6 +29,24 @@
 
 #include "gimp-intl.h"
 
+/**
+ * SECTION:xcf-seek
+ * @Short_description:XCF file seeker functions
+ *
+ * Functions to change the file position in the XCF file
+ */
+
+/**
+ * xcf_seek_pos:
+ * @info:  #XcfInfo structure of the file under work
+ * @pos:   new position, relative to the beginning of the file
+ * @error: Return location for errors
+ *
+ * Changes the file position in the input or output stream to the given
+ * position.
+ *
+ * Returns: %TRUE in case of success; %FALSE otherwise
+ */
 gboolean
 xcf_seek_pos (XcfInfo  *info,
               guint     pos,
@@ -50,6 +68,15 @@ xcf_seek_pos (XcfInfo  *info,
   return TRUE;
 }
 
+/**
+ * xcf_seek_end:
+ * @info: #XcfInfo structure of the file under work
+ * @error: Return location for errors
+ *
+ * Changes the file position in the input or output stream to the file end.
+ *
+ * Returns: %TRUE in case of success; %FALSE otherwise
+ */
 gboolean
 xcf_seek_end (XcfInfo  *info,
               GError  **error)
diff --git a/app/xcf/xcf-write.c b/app/xcf/xcf-write.c
index 6280d35..bd90191 100644
--- a/app/xcf/xcf-write.c
+++ b/app/xcf/xcf-write.c
@@ -28,6 +28,24 @@
 
 #include "gimp-intl.h"
 
+/**
+ * SECTION:xcf-write
+ * @Short_description:XCF writing functions
+ *
+ * Low-level XCF writing functions
+ */
+
+/**
+ * xcf_write_int32:
+ * @fp:     output file stream
+ * @data:   source data array
+ * @count:  number of words to write
+ * @error:  container for occurred errors
+ *
+ * Write @count 4-byte-words from @data to @fp.
+ *
+ * Returns: count (in numbers of bytes, not words)
+ */
 guint
 xcf_write_int32 (FILE           *fp,
                  const guint32  *data,
@@ -57,6 +75,17 @@ xcf_write_int32 (FILE           *fp,
   return count * 4;
 }
 
+/**
+ * xcf_write_float:
+ * @fp:     output file stream
+ * @data:   source data array
+ * @count:  number of words to write
+ * @error:  container for occurred errors
+ *
+ * Write @count float values from @data to @fp.
+ *
+ * Returns: count (in numbers of bytes, not words)
+ */
 guint
 xcf_write_float (FILE           *fp,
                  const gfloat   *data,
@@ -68,6 +97,19 @@ xcf_write_float (FILE           *fp,
                           error);
 }
 
+/**
+ * xcf_write_int8:
+ * @fp:     output file stream
+ * @data:   source data array
+ * @count:  number of bytes to write
+ * @error:  container for occurred errors
+ *
+ * Write @count bytes of unsigned integer from @data to @fp.
+ *
+ * Returns: @count
+ */
+
+/* TODO: shouldn't the return value (i.e. local variable total) mean the number of written bytes? */
 guint
 xcf_write_int8 (FILE           *fp,
                 const guint8   *data,
@@ -80,7 +122,7 @@ xcf_write_int8 (FILE           *fp,
     {
       gint bytes = fwrite ((const gchar*) data, sizeof (gchar), count, fp);
 
-      if (bytes == 0)
+      if (bytes != count)
         {
           g_set_error (error, G_FILE_ERROR, g_file_error_from_errno (errno),
                        _("Error writing XCF: %s"), g_strerror (errno));
@@ -95,6 +137,17 @@ xcf_write_int8 (FILE           *fp,
   return total;
 }
 
+/**
+ * xcf_write_string:
+ * @fp:     output file stream
+ * @data:   source data array
+ * @count:  number of strings to write
+ * @error:  container for occurred errors
+ *
+ * Write @count bytes of unsigned integer from @data to @fp.
+ *
+ * Returns: number of written bytes
+ */
 guint
 xcf_write_string (FILE     *fp,
                   gchar   **data,
diff --git a/app/xcf/xcf.c b/app/xcf/xcf.c
index 08bd8ba..0ff6ecc 100644
--- a/app/xcf/xcf.c
+++ b/app/xcf/xcf.c
@@ -45,6 +45,14 @@
 #include "gimp-intl.h"
 
 
+/**
+ * SECTION:xcf
+ * @Short_description:XCF file loader/saver initialization and finalization
+ *
+ * Functions to initialize and finalize the XCF file loader and saver.
+ *
+ */
+
 typedef GimpImage * GimpXcfLoaderFunc (Gimp     *gimp,
                                        XcfInfo  *info,
                                        GError  **error);
@@ -73,6 +81,12 @@ static GimpXcfLoaderFunc * const xcf_loaders[] =
 };
 
 
+/**
+ * xcf_init:
+ * @gimp: #Gimp instance.
+ *
+ * Registers the functions to load and save XCF files in @gimp's plug-in-manager.
+ */
 void
 xcf_init (Gimp *gimp)
 {
@@ -222,6 +236,22 @@ xcf_init (Gimp *gimp)
   g_object_unref (procedure);
 }
 
+/**
+ * xcf_exit:
+ * @gimp: #Gimp instance
+ *
+ * This function does nothing. It is here to keep the symmetry to xcf_init().
+ * Because the plug-in-manager has taken ownership of the load and save
+ * procedures we don't need to unregister or finalize them here.
+ * This will be done automatically at program exit in gimp_real_exit().
+ *
+ * See also:
+ *
+ * - gimp_real_exit()
+ *
+ * - #GimpPluginManager:gimp_plug_in_manager_exit()
+ *
+ */
 void
 xcf_exit (Gimp *gimp)
 {
diff --git a/devel-docs/app/app-docs.sgml b/devel-docs/app/app-docs.sgml
index cc404c1..29262e1 100644
--- a/devel-docs/app/app-docs.sgml
+++ b/devel-docs/app/app-docs.sgml
@@ -518,7 +518,7 @@
     </chapter>
 
     <chapter id="app-xcf-lowlevel">
-      <title>Lowlevel File Access</title>
+      <title>Low-level File Access</title>
       <xi:include href="xml/xcf-read.xml" />
       <xi:include href="xml/xcf-write.xml" />
       <xi:include href="xml/xcf-seek.xml" />
diff --git a/devel-docs/xcf.txt b/devel-docs/xcf.txt
index e8f5946..c18f8a7 100644
--- a/devel-docs/xcf.txt
+++ b/devel-docs/xcf.txt
@@ -822,6 +822,14 @@ PROP_RESOLUTION (not editing state, but not _really_ essential either)
   files unconditionally, even if the user has not explicitly chosen a
   resolution.
 
+PROP_SAMPLE_POINTS
+  uint32   17       Type identification
+  uint32   plength  Total length of the following payload in bytes
+  ,---------------- Repeat for each sample point:
+  | uint32 x        X coordinate
+  | uint32 y        Y coordinate
+  `--
+
 PROP_UNIT (editing state)
   uint32  22       Type identification
   uint32  4        Four bytes of payload
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]