From aca5f806c4afb6b2f8eb50f06816fa6c2a63a5f4 Mon Sep 17 00:00:00 2001 From: Michael Natterer Date: Wed, 24 Jul 2019 01:18:30 +0200 Subject: [PATCH] libgimp*: lots of doc fixes and new docs for structs and enums --- libgimp/gimp.c | 2 +- libgimp/gimpbrushselectbutton.c | 4 ++-- libgimp/gimpexport.h | 25 +++++++++++++++++++++ libgimp/gimppixbuf.h | 9 ++++++++ libgimp/gimpui.c | 2 +- libgimpbase/gimpbaseenums.h | 2 +- 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/gimpbrowser.c | 6 ++--- libgimpwidgets/gimpbusybox.c | 2 +- libgimpwidgets/gimpbusybox.h | 4 ++++ libgimpwidgets/gimpchainbutton.c | 2 +- libgimpwidgets/gimpcolornotebook.c | 6 ++--- libgimpwidgets/gimpcolorselection.c | 4 ++-- libgimpwidgets/gimpcontroller.h | 35 +++++++++++++++++++++++++++++ libgimpwidgets/gimpmemsizeentry.c | 2 +- libgimpwidgets/gimpwidgets-error.h | 6 +++++ 23 files changed, 176 insertions(+), 22 deletions(-) diff --git a/libgimp/gimp.c b/libgimp/gimp.c index 5e318d068d..eda2a2502e 100644 --- a/libgimp/gimp.c +++ b/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, diff --git a/libgimp/gimpbrushselectbutton.c b/libgimp/gimpbrushselectbutton.c index bd14d00632..8e0fc70352 100644 --- a/libgimp/gimpbrushselectbutton.c +++ b/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 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 018cecc84a..863b768d0e 100644 --- a/libgimp/gimpui.c +++ b/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 diff --git a/libgimpbase/gimpbaseenums.h b/libgimpbase/gimpbaseenums.h index bf53d78c27..9fd389bd02 100644 --- a/libgimpbase/gimpbaseenums.h +++ b/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 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 83eaf78f27..2137142185 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 3e2d451ba7..1477dc61bf 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 b789785eff..485ecce022 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 139dea8fa7..f6dff2a1aa 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 596d6c6329..9e8e8f4f5c 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/gimpbrowser.c b/libgimpwidgets/gimpbrowser.c index d024f4a903..81b39ef9f7 100644 --- a/libgimpwidgets/gimpbrowser.c +++ b/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, diff --git a/libgimpwidgets/gimpbusybox.c b/libgimpwidgets/gimpbusybox.c index d469755715..7332efb856 100644 --- a/libgimpwidgets/gimpbusybox.c +++ b/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, diff --git a/libgimpwidgets/gimpbusybox.h b/libgimpwidgets/gimpbusybox.h index 54376e9346..cf2002855f 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/gimpchainbutton.c b/libgimpwidgets/gimpchainbutton.c index 98083f910b..dade24787e 100644 --- a/libgimpwidgets/gimpchainbutton.c +++ b/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) diff --git a/libgimpwidgets/gimpcolornotebook.c b/libgimpwidgets/gimpcolornotebook.c index d6f08105ca..534ed91f93 100644 --- a/libgimpwidgets/gimpcolornotebook.c +++ b/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) diff --git a/libgimpwidgets/gimpcolorselection.c b/libgimpwidgets/gimpcolorselection.c index a6865a7759..1a7cca95b2 100644 --- a/libgimpwidgets/gimpcolorselection.c +++ b/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) diff --git a/libgimpwidgets/gimpcontroller.h b/libgimpwidgets/gimpcontroller.h index 457ce5b3b8..4a9708d58b 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/gimpmemsizeentry.c b/libgimpwidgets/gimpmemsizeentry.c index 5aae6cbdd2..b90b755662 100644 --- a/libgimpwidgets/gimpmemsizeentry.c +++ b/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) 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