GNOME.org
 

[gimp/gimp-2-10] libgimp*: lots of doc fixes and new docs for structs and enums

commit ff1e645c2fc6cea3ec55255113dc9d770f2b7f9c
Author: Michael Natterer <mitch gimp org>
Date:   Wed Jul 24 01:18:30 2019 +0200

    libgimp*: lots of doc fixes and new docs for structs and enums
    
    (cherry picked from commit aca5f806c4afb6b2f8eb50f06816fa6c2a63a5f4)

 libgimp/gimp.c                     |  2 +-
 libgimp/gimpbrushselectbutton.c    |  4 ++--
 libgimp/gimpexport.h               | 25 +++++++++++++++++++++++++
 libgimp/gimppixbuf.h               |  9 +++++++++
 libgimp/gimpui.c                   |  2 +-
 libgimpbase/gimpbaseenums.h        |  1 +
 libgimpbase/gimpparasite.h         | 17 ++++++++++++-----
 libgimpbase/gimpvaluearray.h       |  9 +++++++++
 libgimpcolor/gimpcolormanaged.h    | 10 ++++++++++
 libgimpcolor/gimpcolortransform.h  | 11 +++++++++++
 libgimpcolor/gimprgb.h             |  6 ++++++
 libgimpconfig/gimpconfig-path.h    |  9 +++++++++
 libgimpconfig/gimpconfigenums.h    | 17 +++++++++++++++++
 libgimpmodule/gimpmodule.h         |  8 +++++++-
 libgimpwidgets/gimpbusybox.c       |  2 +-
 libgimpwidgets/gimpbusybox.h       |  4 ++++
 libgimpwidgets/gimpcontroller.h    | 35 +++++++++++++++++++++++++++++++++++
 libgimpwidgets/gimpwidgets-error.h |  6 ++++++
 18 files changed, 166 insertions(+), 11 deletions(-)
---
diff --git a/libgimp/gimp.c b/libgimp/gimp.c
index d28f86cf15..df9b7f3dfa 100644
--- a/libgimp/gimp.c
+++ b/libgimp/gimp.c
@@ -268,7 +268,7 @@ static gchar             *pdb_error_message  = NULL;
  * and the 'argc' and 'argv' that are passed to "main".
  *
  * Returns: an exit status as defined by the C library,
- *          on success %EXIT_SUCCESS.
+ *          on success EXIT_SUCCESS.
  **/
 gint
 gimp_main (const GimpPlugInInfo *info,
diff --git a/libgimp/gimpbrushselectbutton.c b/libgimp/gimpbrushselectbutton.c
index 99d1c34b1d..45cdee8229 100644
--- a/libgimp/gimpbrushselectbutton.c
+++ b/libgimp/gimpbrushselectbutton.c
@@ -313,8 +313,8 @@ gimp_brush_select_button_init (GimpBrushSelectButton *button)
  * @paint_mode: Initial paint mode.  -1 means to use current paint mode.
  *
  * Creates a new #GtkWidget that completely controls the selection of
- * a #GimpBrush.  This widget is suitable for placement in a table in
- * a plug-in dialog.
+ * a brush. This widget is suitable for placement in a table in a
+ * plug-in dialog.
  *
  * Returns: A #GtkWidget that you can use in your UI.
  *
diff --git a/libgimp/gimpexport.h b/libgimp/gimpexport.h
index 11d4dff187..8b8c7545b1 100644
--- a/libgimp/gimpexport.h
+++ b/libgimp/gimpexport.h
@@ -31,6 +31,20 @@ G_BEGIN_DECLS
 /* For information look into the C source or the html documentation */
 
 
+/**
+ * GimpExportCapabilities:
+ * @GIMP_EXPORT_CAN_HANDLE_RGB:                 Handles RGB images
+ * @GIMP_EXPORT_CAN_HANDLE_GRAY:                Handles grayscale images
+ * @GIMP_EXPORT_CAN_HANDLE_INDEXED:             Handles indexed images
+ * @GIMP_EXPORT_CAN_HANDLE_BITMAP:              Handles two-color indexed images
+ * @GIMP_EXPORT_CAN_HANDLE_ALPHA:               Handles alpha channels
+ * @GIMP_EXPORT_CAN_HANDLE_LAYERS:              Hanldes layers
+ * @GIMP_EXPORT_CAN_HANDLE_LAYERS_AS_ANIMATION: Handles aminations of layers
+ * @GIMP_EXPORT_CAN_HANDLE_LAYER_MASKS:         Handles layer masks
+ * @GIMP_EXPORT_NEEDS_ALPHA:                    Needs alpha channels
+ *
+ * The types of images and layers an export procedure can handle
+ **/
 typedef enum
 {
   GIMP_EXPORT_CAN_HANDLE_RGB                 = 1 << 0,
@@ -44,6 +58,15 @@ typedef enum
   GIMP_EXPORT_NEEDS_ALPHA                    = 1 << 8
 } GimpExportCapabilities;
 
+
+/**
+ * GimpExportReturn:
+ * @GIMP_EXPORT_CANCEL: The export was cancelled
+ * @GIMP_EXPORT_IGNORE: The image is unmodified but export shall continue anyway
+ * @GIMP_EXPORT_EXPORT: The chosen transforms were applied to the image
+ *
+ * Possible return values of gimp_export_image().
+ **/
 typedef enum
 {
   GIMP_EXPORT_CANCEL,
@@ -51,10 +74,12 @@ typedef enum
   GIMP_EXPORT_EXPORT
 } GimpExportReturn;
 
+
 GimpExportReturn   gimp_export_image                   (gint32                 *image_ID,
                                                         gint32                 *drawable_ID,
                                                         const gchar            *format_name,
                                                         GimpExportCapabilities  capabilities);
+
 GtkWidget        * gimp_export_dialog_new              (const gchar            *format_name,
                                                         const gchar            *role,
                                                         const gchar            *help_id);
diff --git a/libgimp/gimppixbuf.h b/libgimp/gimppixbuf.h
index 3c5c6a47dd..b7347844fd 100644
--- a/libgimp/gimppixbuf.h
+++ b/libgimp/gimppixbuf.h
@@ -31,6 +31,15 @@ G_BEGIN_DECLS
 /* For information look into the C source or the html documentation */
 
 
+/**
+ * GimpPixbufTransparency:
+ * @GIMP_PIXBUF_KEEP_ALPHA:   Create a pixbuf with alpha
+ * @GIMP_PIXBUF_SMALL_CHECKS: Show transparency as small checks
+ * @GIMP_PIXBUF_LARGE_CHECKS: Show transparency as large checks
+ *
+ * How to deal with transparency when creating thubnail pixbufs from
+ * images and drawables.
+ **/
 typedef enum
 {
   GIMP_PIXBUF_KEEP_ALPHA,
diff --git a/libgimp/gimpui.c b/libgimp/gimpui.c
index 11bccd2e01..b6589d7938 100644
--- a/libgimp/gimpui.c
+++ b/libgimp/gimpui.c
@@ -209,7 +209,7 @@ gimp_ui_get_foreign_window (guint32 window)
 
 /**
  * gimp_ui_get_display_window:
- * @gdisp_ID: a #GimpDisplay ID.
+ * @gdisp_ID: a GimpDisplay ID.
  *
  * Returns the #GdkWindow of a display window. The purpose is to allow
  * to make plug-in dialogs transient to the image display as explained
diff --git a/libgimpbase/gimpbaseenums.h b/libgimpbase/gimpbaseenums.h
index 4f3d9fafbe..b3c6fb75ad 100644
--- a/libgimpbase/gimpbaseenums.h
+++ b/libgimpbase/gimpbaseenums.h
@@ -603,6 +603,7 @@ typedef enum
  * @GIMP_GRADIENT_SEGMENT_SINE:              Sinusoidal
  * @GIMP_GRADIENT_SEGMENT_SPHERE_INCREASING: Spherical (increasing)
  * @GIMP_GRADIENT_SEGMENT_SPHERE_DECREASING: Spherical (decreasing)
+ * @GIMP_GRADIENT_SEGMENT_STEP:              Step
  *
  * Transition functions for gradient segments.
  **/
diff --git a/libgimpbase/gimpparasite.h b/libgimpbase/gimpparasite.h
index 8d4bbe44b6..3c17bf78bb 100644
--- a/libgimpbase/gimpparasite.h
+++ b/libgimpbase/gimpparasite.h
@@ -68,13 +68,20 @@ GParamSpec * gimp_param_spec_parasite      (const gchar  *name,
 #define GIMP_PARASITE_GRANDPARENT_UNDOABLE   (GIMP_PARASITE_UNDOABLE << 16)
 
 
+/**
+ * GimpParasite:
+ * @name:  the parasite name, USE A UNIQUE PREFIX
+ * @flags: the parasite flags, like save in XCF etc.
+ * @size:  the parasite size in bytes
+ * @data:  the parasite data, the owner os the parasite is responsible
+ *   for tracking byte order and internal structure
+ **/
 struct _GimpParasite
 {
-  gchar    *name;   /* The name of the parasite. USE A UNIQUE PREFIX! */
-  guint32   flags;  /* save Parasite in XCF file, etc.                */
-  guint32   size;   /* amount of data                                 */
-  gpointer  data;   /* a pointer to the data.  plugin is              *
-                     * responsible for tracking byte order            */
+  gchar    *name;
+  guint32   flags;
+  guint32   size;
+  gpointer  data;
 };
 
 
diff --git a/libgimpbase/gimpvaluearray.h b/libgimpbase/gimpvaluearray.h
index 9f1c2a61ac..88674ab885 100644
--- a/libgimpbase/gimpvaluearray.h
+++ b/libgimpbase/gimpvaluearray.h
@@ -74,6 +74,15 @@ void             gimp_value_array_truncate (GimpValueArray       *value_array,
 
 typedef struct _GimpParamSpecValueArray GimpParamSpecValueArray;
 
+/**
+ * GimpParamSpecValueArray:
+ * @parent_instance:  private #GParamSpec portion
+ * @element_spec:     the #GParamSpec of the array elements
+ * @fixed_n_elements: default length of the array
+ *
+ * A #GParamSpec derived structure that contains the meta data for value array
+ *   character properties
+ **/
 struct _GimpParamSpecValueArray
 {
   GParamSpec  parent_instance;
diff --git a/libgimpcolor/gimpcolormanaged.h b/libgimpcolor/gimpcolormanaged.h
index 69818141c9..d24e0c8ac4 100644
--- a/libgimpcolor/gimpcolormanaged.h
+++ b/libgimpcolor/gimpcolormanaged.h
@@ -39,6 +39,16 @@ G_BEGIN_DECLS
 
 typedef struct _GimpColorManagedInterface GimpColorManagedInterface;
 
+/**
+ * GimpColorManagedInterface:
+ * @base_iface: The parent interface
+ * @get_icc_profile: Returns the ICC profile of the pixels managed by
+ *                   the object
+ * @profile_changed: This signal is emitted when the object's color profile
+ *                   has changed
+ * @get_color_profile: Returns the #GimpColorProfile of the pixels managed
+ *                     by the object
+ **/
 struct _GimpColorManagedInterface
 {
   GTypeInterface  base_iface;
diff --git a/libgimpcolor/gimpcolortransform.h b/libgimpcolor/gimpcolortransform.h
index f4b40a52b1..c579470b33 100644
--- a/libgimpcolor/gimpcolortransform.h
+++ b/libgimpcolor/gimpcolortransform.h
@@ -32,6 +32,17 @@ G_BEGIN_DECLS
 /* For information look into the C source or the html documentation */
 
 
+/**
+ * GimpColorTransformFlags:
+ * @GIMP_COLOR_TRANSFORM_FLAGS_NOOPTIMIZE: optimize for accuracy rather
+ *   than for speed
+ * @GIMP_COLOR_TRANSFORM_FLAGS_GAMUT_CHECK: mark out of gamut colors in the
+ *   transform result
+ * @GIMP_COLOR_TRANSFORM_FLAGS_BLACK_POINT_COMPENSATION: do black point
+ *   compensation
+ *
+ * Flags for modifying #GimpColorTransform's behavior.
+ **/
 typedef enum
 {
   GIMP_COLOR_TRANSFORM_FLAGS_NOOPTIMIZE               = 0x0100,
diff --git a/libgimpcolor/gimprgb.h b/libgimpcolor/gimprgb.h
index cb6cf191d4..b1ca07e8a3 100644
--- a/libgimpcolor/gimprgb.h
+++ b/libgimpcolor/gimprgb.h
@@ -65,6 +65,12 @@ gboolean     gimp_param_spec_rgb_has_alpha (GParamSpec     *pspec);
 
 /*  RGB and RGBA color types and operations taken from LibGCK  */
 
+/**
+ * GimpRGBCompositeMode:
+ * @GIMP_RGB_COMPOSITE_NONE: don't do compositing
+ * @GIMP_RGB_COMPOSITE_NORMAL: composite on top
+ * @GIMP_RGB_COMPOSITE_BEHIND: composite behind
+ **/
 typedef enum
 {
   GIMP_RGB_COMPOSITE_NONE = 0,
diff --git a/libgimpconfig/gimpconfig-path.h b/libgimpconfig/gimpconfig-path.h
index ab99d32b66..1b157f9e67 100644
--- a/libgimpconfig/gimpconfig-path.h
+++ b/libgimpconfig/gimpconfig-path.h
@@ -46,6 +46,15 @@ GType               gimp_config_path_get_type        (void) G_GNUC_CONST;
  * GIMP_TYPE_PARAM_CONFIG_PATH
  */
 
+/**
+ * GimpConfigPathType:
+ * @GIMP_CONFIG_PATH_FILE:      A single file
+ * @GIMP_CONFIG_PATH_FILE_LIST: A list of files
+ * @GIMP_CONFIG_PATH_DIR:       A single folder
+ * @GIMP_CONFIG_PATH_DIR_LIST:  A list of folders
+ *
+ * Types of config paths.
+ **/
 typedef enum
 {
   GIMP_CONFIG_PATH_FILE,
diff --git a/libgimpconfig/gimpconfigenums.h b/libgimpconfig/gimpconfigenums.h
index b2544e83bc..ec5c7595ae 100644
--- a/libgimpconfig/gimpconfigenums.h
+++ b/libgimpconfig/gimpconfigenums.h
@@ -27,6 +27,14 @@
 
 GType gimp_color_management_mode_get_type (void) G_GNUC_CONST;
 
+/**
+ * GimpColorManagementMode:
+ * @GIMP_COLOR_MANAGEMENT_OFF:       Color management is off
+ * @GIMP_COLOR_MANAGEMENT_DISPLAY:   Color managed display
+ * @GIMP_COLOR_MANAGEMENT_SOFTPROOF: Soft-proofing
+ *
+ * Modes of color management.
+ **/
 typedef enum
 {
   GIMP_COLOR_MANAGEMENT_OFF,       /*< desc="No color management"   >*/
@@ -39,6 +47,15 @@ typedef enum
 
 GType gimp_color_rendering_intent_get_type (void) G_GNUC_CONST;
 
+/**
+ * GimpColorRenderingIntent:
+ * @GIMP_COLOR_RENDERING_INTENT_PERCEPTUAL:            Preceptual
+ * @GIMP_COLOR_RENDERING_INTENT_RELATIVE_COLORIMETRIC: Relative colorimetric
+ * @GIMP_COLOR_RENDERING_INTENT_SATURATION:            Saturation
+ * @GIMP_COLOR_RENDERING_INTENT_ABSOLUTE_COLORIMETRIC: Absolute colorimetric
+ *
+ * Intents for color management.
+ **/
 typedef enum
 {
   GIMP_COLOR_RENDERING_INTENT_PERCEPTUAL,            /*< desc="Perceptual"            >*/
diff --git a/libgimpmodule/gimpmodule.h b/libgimpmodule/gimpmodule.h
index 7f37345f8a..d19ba1f365 100644
--- a/libgimpmodule/gimpmodule.h
+++ b/libgimpmodule/gimpmodule.h
@@ -79,9 +79,15 @@ typedef enum
 
 GQuark  gimp_module_error_quark (void) G_GNUC_CONST;
 
+/**
+ * GimpModuleError:
+ * @GIMP_MODULE_FAILED: Generic error condition
+ *
+ * Types of errors returned by modules
+ **/
 typedef enum
 {
-  GIMP_MODULE_FAILED             /* generic error condition */
+  GIMP_MODULE_FAILED
 } GimpModuleError;
 
 
diff --git a/libgimpwidgets/gimpbusybox.c b/libgimpwidgets/gimpbusybox.c
index 33255d189c..8c11bd2ddd 100644
--- a/libgimpwidgets/gimpbusybox.c
+++ b/libgimpwidgets/gimpbusybox.c
@@ -88,7 +88,7 @@ gimp_busy_box_class_init (GimpBusyBoxClass *klass)
    * Specifies the displayed message.
    *
    * Since: 2.10.4
-   */
+   **/
   g_object_class_install_property (object_class, PROP_MESSAGE,
                                    g_param_spec_string ("message",
                                                         NULL, NULL,
diff --git a/libgimpwidgets/gimpbusybox.h b/libgimpwidgets/gimpbusybox.h
index 5de6e25804..f2779add32 100644
--- a/libgimpwidgets/gimpbusybox.h
+++ b/libgimpwidgets/gimpbusybox.h
@@ -55,6 +55,10 @@ struct _GimpBusyBoxClass
   void (* _gimp_reserved2) (void);
   void (* _gimp_reserved3) (void);
   void (* _gimp_reserved4) (void);
+  void (* _gimp_reserved5) (void);
+  void (* _gimp_reserved6) (void);
+  void (* _gimp_reserved7) (void);
+  void (* _gimp_reserved8) (void);
 };
 
 
diff --git a/libgimpwidgets/gimpcontroller.h b/libgimpwidgets/gimpcontroller.h
index c51d0a0853..b258084ae1 100644
--- a/libgimpwidgets/gimpcontroller.h
+++ b/libgimpwidgets/gimpcontroller.h
@@ -50,6 +50,15 @@ typedef struct _GimpControllerEventTrigger GimpControllerEventTrigger;
 typedef struct _GimpControllerEventValue   GimpControllerEventValue;
 typedef union  _GimpControllerEvent        GimpControllerEvent;
 
+/**
+ * GimpControllerEventAny:
+ * @type:     The event's #GimpControllerEventType
+ * @source:   The event's source #GimpController
+ * @event_id: The event's ID
+ *
+ * Generic controller event. Every event has these three members at the
+ * beginning of its struct
+ **/
 struct _GimpControllerEventAny
 {
   GimpControllerEventType  type;
@@ -57,6 +66,14 @@ struct _GimpControllerEventAny
   gint                     event_id;
 };
 
+/**
+ * GimpControllerEventTrigger:
+ * @type:     The event's #GimpControllerEventType
+ * @source:   The event's source #GimpController
+ * @event_id: The event's ID
+ *
+ * Trigger controller event.
+ **/
 struct _GimpControllerEventTrigger
 {
   GimpControllerEventType  type;
@@ -64,6 +81,15 @@ struct _GimpControllerEventTrigger
   gint                     event_id;
 };
 
+/**
+ * GimpControllerEventValue:
+ * @type:     The event's #GimpControllerEventType
+ * @source:   The event's source #GimpController
+ * @event_id: The event's ID
+ * @value:    The event's value
+ *
+ * Value controller event.
+ **/
 struct _GimpControllerEventValue
 {
   GimpControllerEventType  type;
@@ -72,6 +98,15 @@ struct _GimpControllerEventValue
   GValue                   value;
 };
 
+/**
+ * GimpControllerEvent:
+ * @type:    The event type
+ * @any:     GimpControllerEventAny
+ * @trigger: GimpControllerEventTrigger
+ * @value:   GimpControllerEventValue
+ *
+ * A union to hjold all event event types
+ **/
 union _GimpControllerEvent
 {
   GimpControllerEventType    type;
diff --git a/libgimpwidgets/gimpwidgets-error.h b/libgimpwidgets/gimpwidgets-error.h
index cff82981fa..8722106cb7 100644
--- a/libgimpwidgets/gimpwidgets-error.h
+++ b/libgimpwidgets/gimpwidgets-error.h
@@ -29,6 +29,12 @@
 G_BEGIN_DECLS
 
 
+/**
+ * GimpWidgetsError:
+ * @GIMP_WIDGETS_PARSE_ERROR: A parse error has occured
+ *
+ * Types of errors returned by libgimpwidgets functions
+ **/
 typedef enum
 {
   GIMP_WIDGETS_PARSE_ERROR
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]