libgimp*: lots of doc fixes and new docs for structs and enums

libgimp/gimp.c

@@ -266,7 +266,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,

libgimp/gimpbrushselectbutton.c

@@ -315,8 +315,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 brush. This widget is suitable for placement in a table in a
- * a plug-in dialog.
+ * plug-in dialog.
  *
  * Returns: A #GtkWidget that you can use in your UI.
  *

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);

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,

libgimp/gimpui.c

@@ -195,7 +195,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

libgimpbase/gimpbaseenums.h

@@ -473,6 +473,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.
  **/
@@ -971,7 +972,6 @@ typedef enum
  * @GIMP_PRECISION_DOUBLE_LINEAR:     64-bit linear floating point
  * @GIMP_PRECISION_DOUBLE_NON_LINEAR: 64-bit non-linear floating point
  * @GIMP_PRECISION_DOUBLE_PERCEPTUAL: 64-bit perceptual floating point
- *
  * @GIMP_PRECISION_U8_GAMMA:      deprecated alias for
  *                                @GIMP_PRECISION_U8_NON_LINEAR
  * @GIMP_PRECISION_U16_GAMMA:     deprecated alias for

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! */
+  gchar    *name;
-  guint32   flags;  /* save Parasite in XCF file, etc.                */
+  guint32   flags;
-  guint32   size;   /* amount of data                                 */
+  guint32   size;
-  gpointer  data;   /* a pointer to the data.  plugin is              *
+  gpointer  data;
-                     * responsible for tracking byte order            */
 };
 
 

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;

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;

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,

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,

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,

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"            >*/

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;
 
 

libgimpwidgets/gimpbrowser.c

@@ -295,7 +295,7 @@ gimp_browser_add_search_types (GimpBrowser *browser,
  *
  * Returns: The left vbox.
  *
- * Since: GIMP 3.0
+ * Since: 3.0
  **/
 GtkWidget *
 gimp_browser_get_left_vbox (GimpBrowser *browser)
@@ -315,7 +315,7 @@ gimp_browser_get_left_vbox (GimpBrowser *browser)
  *
  * Returns: The right vbox.
  *
- * Since: GIMP 3.0
+ * Since: 3.0
  **/
 GtkWidget *
 gimp_browser_get_right_vbox (GimpBrowser *browser)
@@ -336,7 +336,7 @@ gimp_browser_get_right_vbox (GimpBrowser *browser)
  *
  * Sets the search summary text.
  *
- * Since: GIMP 3.0
+ * Since: 3.0
  **/
 void
 gimp_browser_set_search_summary (GimpBrowser *browser,

libgimpwidgets/gimpbusybox.c

@@ -87,7 +87,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,

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);
 };
 
 

libgimpwidgets/gimpchainbutton.c

@@ -425,7 +425,7 @@ gimp_chain_button_get_active (GimpChainButton *button)
  *
  * Returns: The #GimpChainButton's button.
  *
- * Since: GIMP 3.0
+ * Since: 3.0
  */
 GtkWidget *
 gimp_chain_button_get_button (GimpChainButton *button)

libgimpwidgets/gimpcolornotebook.c

@@ -554,7 +554,7 @@ gimp_color_notebook_set_has_page (GimpColorNotebook *notebook,
  *
  * Return value: The #GtkNotebook inside.
  *
- * Since: GIMP 3.0
+ * Since: 3.0
  **/
 GtkWidget *
 gimp_color_notebook_get_notebook (GimpColorNotebook *notebook)
@@ -570,7 +570,7 @@ gimp_color_notebook_get_notebook (GimpColorNotebook *notebook)
  *
  * Return value: The notebook's list of #GimpColorSelector's.
  *
- * Since: GIMP 3.0
+ * Since: 3.0
  **/
 GList *
 gimp_color_notebook_get_selectors (GimpColorNotebook *notebook)
@@ -586,7 +586,7 @@ gimp_color_notebook_get_selectors (GimpColorNotebook *notebook)
  *
  * Return value: The active page's #GimpColorSelector.
  *
- * Since: GIMP 3.0
+ * Since: 3.0
  **/
 GimpColorSelector *
 gimp_color_notebook_get_current_selector (GimpColorNotebook *notebook)

libgimpwidgets/gimpcolorselection.c

@@ -597,7 +597,7 @@ gimp_color_selection_set_config (GimpColorSelection *selection,
  *
  * Returns: The selection's #GimpColorNotebook.
  *
- * Since: GIMP 3.0
+ * Since: 3.0
  */
 GtkWidget *
 gimp_color_selection_get_notebook (GimpColorSelection *selection)
@@ -613,7 +613,7 @@ gimp_color_selection_get_notebook (GimpColorSelection *selection)
  *
  * Returns: The selection's right #GtkBox which contains the color scales.
  *
- * Since: GIMP 3.0
+ * Since: 3.0
  */
 GtkWidget *
 gimp_color_selection_get_right_vbox (GimpColorSelection *selection)

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;

libgimpwidgets/gimpmemsizeentry.c

@@ -299,7 +299,7 @@ gimp_memsize_entry_get_value (GimpMemsizeEntry *entry)
  *
  * Returns: the entry's #GtkSpinbutton.
  *
- * Since: GIMP 3.0
+ * Since: 3.0
  **/
 GtkWidget *
 gimp_memsize_entry_get_spinbutton (GimpMemsizeEntry *entry)

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