From 3411c7b63a7d3e25118e19dc74568c69f630e3c5 Mon Sep 17 00:00:00 2001 From: Michael Natterer Date: Tue, 29 Jun 2010 19:13:40 +0200 Subject: [PATCH] libgimpbase: move docs from template files to inline comments and remove all template files. Also fixed all gtk-doc warnings and fixed/added some docs. --- configure.ac | 40 +++++++++++++ devel-docs/libgimpbase/.gitignore | 1 + .../libgimpbase/libgimpbase-sections.txt | 3 + devel-docs/libgimpbase/tmpl/.gitignore | 2 - .../libgimpbase/tmpl/gimpbaseenums.sgml | 7 ++- .../libgimpbase/tmpl/gimpbasetypes.sgml | 7 ++- devel-docs/libgimpbase/tmpl/gimpchecks.sgml | 17 +++--- devel-docs/libgimpbase/tmpl/gimpcpuaccel.sgml | 4 ++ .../libgimpbase/tmpl/gimpdatafiles.sgml | 7 ++- devel-docs/libgimpbase/tmpl/gimpenv.sgml | 14 ++++- devel-docs/libgimpbase/tmpl/gimplimits.sgml | 26 +++------ devel-docs/libgimpbase/tmpl/gimpmemsize.sgml | 9 ++- devel-docs/libgimpbase/tmpl/gimpparam.sgml | 13 +++-- devel-docs/libgimpbase/tmpl/gimpparasite.sgml | 9 +-- .../libgimpbase/tmpl/gimpparasiteio.sgml | 26 ++++++++- .../libgimpbase/tmpl/gimprectangle.sgml | 3 + devel-docs/libgimpbase/tmpl/gimpsignal.sgml | 16 +++--- devel-docs/libgimpbase/tmpl/gimpunit.sgml | 39 ++++++++++--- devel-docs/libgimpbase/tmpl/gimputils.sgml | 5 +- devel-docs/libgimpbase/tmpl/gimpversion.sgml | 10 ++-- libgimpbase/gimpbaseenums.h | 9 +++ libgimpbase/gimpbasetypes.c | 23 ++++++-- libgimpbase/gimpbasetypes.h | 18 ++++++ libgimpbase/gimpchecks.c | 10 ++++ libgimpbase/gimpchecks.h | 37 +++++++++--- libgimpbase/gimpcpuaccel.c | 9 +++ libgimpbase/gimpdatafiles.c | 9 +++ libgimpbase/gimpdatafiles.h | 13 +++++ libgimpbase/gimpenv.c | 10 ++++ libgimpbase/gimplimits.h | 57 +++++++++++++++++-- libgimpbase/gimpmemsize.c | 9 +++ libgimpbase/gimpmemsize.h | 8 ++- libgimpbase/gimpparam.h | 32 ++++++++++- libgimpbase/gimpparasite.c | 13 +++++ libgimpbase/gimpparasiteio.c | 12 ++++ libgimpbase/gimpparasiteio.h | 6 +- libgimpbase/gimprectangle.c | 9 +++ libgimpbase/gimpsignal.c | 10 ++++ libgimpbase/gimpsignal.h | 14 +++-- libgimpbase/gimpunit.c | 22 ++++++- libgimpbase/gimpunit.h | 10 ++-- libgimpbase/gimputils.c | 11 +++- 42 files changed, 496 insertions(+), 113 deletions(-) delete mode 100644 devel-docs/libgimpbase/tmpl/.gitignore diff --git a/configure.ac b/configure.ac index dd73b9ca0d..0a6d9c7b07 100644 --- a/configure.ac +++ b/configure.ac @@ -1924,14 +1924,54 @@ AC_CONFIG_COMMANDS([libgimpbase/gimpversion.h], [ G_BEGIN_DECLS +/** + * SECTION: gimpversion + * @title: gimpversion + * @short_description: Macros and constants useful for determining + * GIMP's version number and capabilities. + * + * Macros and constants useful for determining GIMP's version number and + * capabilities. + **/ + _______EOF cat >>$outfile <<_______EOF +/** + * GIMP_MAJOR_VERSION: + * + * The major GIMP version number. + **/ #define GIMP_MAJOR_VERSION ($gimp_major_ver) + +/** + * GIMP_MINOR_VERSION: + * + * The minor GIMP version number. + **/ #define GIMP_MINOR_VERSION ($gimp_minor_ver) + +/** + * GIMP_MICRO_VERSION: + * + * The micro GIMP version number. + **/ #define GIMP_MICRO_VERSION ($gimp_micro_ver) + +/** + * GIMP_VERSION: + * + * The GIMP version as a string. + **/ #define GIMP_VERSION "$gimp_ver" + +/** + * GIMP_API_VERSION: + * + * Since: GIMP 2.2 + **/ #define GIMP_API_VERSION "$gimp_api_ver" + _______EOF cat >>$outfile <<\_______EOF diff --git a/devel-docs/libgimpbase/.gitignore b/devel-docs/libgimpbase/.gitignore index d99fe4dac7..9e029b2475 100644 --- a/devel-docs/libgimpbase/.gitignore +++ b/devel-docs/libgimpbase/.gitignore @@ -12,6 +12,7 @@ /libgimpbase-undeclared.txt /libgimpbase-undocumented.txt /html +/tmpl /xml /version /*.bak diff --git a/devel-docs/libgimpbase/libgimpbase-sections.txt b/devel-docs/libgimpbase/libgimpbase-sections.txt index 81b255a8c2..e6c443ccd9 100644 --- a/devel-docs/libgimpbase/libgimpbase-sections.txt +++ b/devel-docs/libgimpbase/libgimpbase-sections.txt @@ -232,6 +232,7 @@ gimp_param_parasite_get_type
gimpparasiteio GIMP_PIXPIPE_MAXDIM +GimpPixPipeParams gimp_pixpipe_params_init gimp_pixpipe_params_parse gimp_pixpipe_params_build @@ -258,6 +259,8 @@ gimp_unit_get_symbol gimp_unit_get_abbreviation gimp_unit_get_singular gimp_unit_get_plural +gimp_pixels_to_units +gimp_units_to_pixels GIMP_TYPE_UNIT GIMP_TYPE_PARAM_UNIT GIMP_IS_PARAM_SPEC_UNIT diff --git a/devel-docs/libgimpbase/tmpl/.gitignore b/devel-docs/libgimpbase/tmpl/.gitignore deleted file mode 100644 index 0bbe72dca9..0000000000 --- a/devel-docs/libgimpbase/tmpl/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -/libgimpbase-unused.sgml -/*.bak diff --git a/devel-docs/libgimpbase/tmpl/gimpbaseenums.sgml b/devel-docs/libgimpbase/tmpl/gimpbaseenums.sgml index 7531822b95..1cbc7ce7f8 100644 --- a/devel-docs/libgimpbase/tmpl/gimpbaseenums.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpbaseenums.sgml @@ -2,11 +2,11 @@ gimpbaseenums -Basic GIMP enumeration data types. + -Basic GIMP enumeration data types. + @@ -17,6 +17,9 @@ Basic GIMP enumeration data types. + + + diff --git a/devel-docs/libgimpbase/tmpl/gimpbasetypes.sgml b/devel-docs/libgimpbase/tmpl/gimpbasetypes.sgml index 83cbefa344..abeec3a9d8 100644 --- a/devel-docs/libgimpbase/tmpl/gimpbasetypes.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpbasetypes.sgml @@ -2,11 +2,11 @@ gimpbasetypes -Translation between gettext translation domain identifier and GType. + -Translation between gettext translation domain identifier and GType. + @@ -17,6 +17,9 @@ Translation between gettext translation domain identifier and GType. + + + diff --git a/devel-docs/libgimpbase/tmpl/gimpchecks.sgml b/devel-docs/libgimpbase/tmpl/gimpchecks.sgml index 94cec1ed8a..5ab8eb8067 100644 --- a/devel-docs/libgimpbase/tmpl/gimpchecks.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpchecks.sgml @@ -2,11 +2,11 @@ gimpchecks -Constants and functions related to rendering checkerboards. + -Constants and functions related to rendering checkerboards. + @@ -17,32 +17,33 @@ Constants and functions related to rendering checkerboards. + + + -The default checkerboard size in pixels. This is configurable in the -core but GIMP plug-ins can't access the user preference and should use -this constant instead. + -The default small checkerboard size in pixels. + -The dark gray value for the default checkerboard pattern. + -The light gray value for the default checkerboard pattern. + diff --git a/devel-docs/libgimpbase/tmpl/gimpcpuaccel.sgml b/devel-docs/libgimpbase/tmpl/gimpcpuaccel.sgml index a58e7bdb1a..b4ea4eb3fa 100644 --- a/devel-docs/libgimpbase/tmpl/gimpcpuaccel.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpcpuaccel.sgml @@ -17,6 +17,9 @@ gimpcpuaccel + + + @@ -36,6 +39,7 @@ gimpcpuaccel +@void: @Returns: diff --git a/devel-docs/libgimpbase/tmpl/gimpdatafiles.sgml b/devel-docs/libgimpbase/tmpl/gimpdatafiles.sgml index 88cd0ece6d..f35425b899 100644 --- a/devel-docs/libgimpbase/tmpl/gimpdatafiles.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpdatafiles.sgml @@ -2,11 +2,11 @@ gimpdatafiles -Functions to handle GIMP data files. + -Functions to handle GIMP data files. + @@ -17,6 +17,9 @@ Functions to handle GIMP data files. + + + diff --git a/devel-docs/libgimpbase/tmpl/gimpenv.sgml b/devel-docs/libgimpbase/tmpl/gimpenv.sgml index 6a39cbc06c..ff2f66c1c7 100644 --- a/devel-docs/libgimpbase/tmpl/gimpenv.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpenv.sgml @@ -2,12 +2,11 @@ gimpenv -Functions to access the GIMP environment. + -A set of functions to find the locations of GIMP's data directories and -configuration files. + @@ -18,6 +17,9 @@ configuration files. + + + @@ -31,6 +33,7 @@ configuration files. +@void: @Returns: @@ -39,6 +42,7 @@ configuration files. +@void: @Returns: @@ -47,6 +51,7 @@ configuration files. +@void: @Returns: @@ -55,6 +60,7 @@ configuration files. +@void: @Returns: @@ -63,6 +69,7 @@ configuration files. +@void: @Returns: @@ -89,6 +96,7 @@ configuration files. +@void: @Returns: diff --git a/devel-docs/libgimpbase/tmpl/gimplimits.sgml b/devel-docs/libgimpbase/tmpl/gimplimits.sgml index d027b78d4d..1a2252b541 100644 --- a/devel-docs/libgimpbase/tmpl/gimplimits.sgml +++ b/devel-docs/libgimpbase/tmpl/gimplimits.sgml @@ -2,11 +2,10 @@ gimplimits -Boundaries of some GIMP data types and some global constants. + -Boundaries of some GIMP data types and some global constants. @@ -18,47 +17,40 @@ Boundaries of some GIMP data types and some global constants. + + + -The minimum width and height of a GIMP image in pixels. + -The maximum width and height of a GIMP image in pixels. This is a -somewhat arbitray value that can be used when an upper value for pixel -sizes is needed; for example to give a spin button an upper limit. + -The minimum resolution of a GIMP image in pixels per inch. This is a -somewhat arbitray value that can be used to when a lower value for a -resolution is needed. GIMP will not accept resolutions smaller than -this value. + -The maximum resolution of a GIMP image in pixels per inch. This is a -somewhat arbitray value that can be used to when an upper value for a -resolution is needed. GIMP will not accept resolutions larger than -this value. + -A large but arbitrary value that can be used when an upper limit for a -memory size (in bytes) is needed. It is smaller than %G_MAXDOUBLE since -the #GimpMemsizeEntry doesn't handle larger values. + diff --git a/devel-docs/libgimpbase/tmpl/gimpmemsize.sgml b/devel-docs/libgimpbase/tmpl/gimpmemsize.sgml index aea7dc521a..93fb0d3c7c 100644 --- a/devel-docs/libgimpbase/tmpl/gimpmemsize.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpmemsize.sgml @@ -2,11 +2,11 @@ gimpmemsize -Functions to (de)serialize a given memory size. + -Functions to (de)serialize a given memory size. + @@ -17,6 +17,9 @@ Functions to (de)serialize a given memory size. + + + @@ -47,7 +50,7 @@ Functions to (de)serialize a given memory size. -#GIMP_TYPE_MEMSIZE is a #GType derived from #G_TYPE_UINT64. + diff --git a/devel-docs/libgimpbase/tmpl/gimpparam.sgml b/devel-docs/libgimpbase/tmpl/gimpparam.sgml index 6bef4c2c1e..6d82fe7c72 100644 --- a/devel-docs/libgimpbase/tmpl/gimpparam.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpparam.sgml @@ -2,7 +2,7 @@ gimpparam -Definitions of useful #GParamFlags. + @@ -17,30 +17,33 @@ Definitions of useful #GParamFlags. + + + -Since: GIMP 2.4 + -Since: GIMP 2.4 + -Since: GIMP 2.4 + -Since: GIMP 2.4 + diff --git a/devel-docs/libgimpbase/tmpl/gimpparasite.sgml b/devel-docs/libgimpbase/tmpl/gimpparasite.sgml index 56b9380078..5d4d62482c 100644 --- a/devel-docs/libgimpbase/tmpl/gimpparasite.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpparasite.sgml @@ -2,23 +2,24 @@ gimpparasite -Arbitrary pieces of data which can be attached to various GIMP objects. + -Arbitrary pieces of data which can be attached to various GIMP objects. -gimp_image_parasite_attach(), gimp_drawable_parasite_attach(), -gimp_parasite_attach() and their related functions. + + + + diff --git a/devel-docs/libgimpbase/tmpl/gimpparasiteio.sgml b/devel-docs/libgimpbase/tmpl/gimpparasiteio.sgml index 4105e626d2..76b380d3ba 100644 --- a/devel-docs/libgimpbase/tmpl/gimpparasiteio.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpparasiteio.sgml @@ -2,22 +2,24 @@ gimpparasiteio -Utility functions to (de)serialize certain C structures to/from #GimpParasite's. + -Utility functions to (de)serialize certain C structures to/from #GimpParasite's. -#GimpParasite + + + + @@ -25,6 +27,24 @@ Utility functions to (de)serialize certain C structures to/from #GimpParasite's. + + + + + +@step: +@ncells: +@dim: +@cols: +@rows: +@cellwidth: +@cellheight: +@placement: +@free_placement_string: +@rank: +@selection: +@free_selection_string: + diff --git a/devel-docs/libgimpbase/tmpl/gimprectangle.sgml b/devel-docs/libgimpbase/tmpl/gimprectangle.sgml index 586fa4466f..794e9423fc 100644 --- a/devel-docs/libgimpbase/tmpl/gimprectangle.sgml +++ b/devel-docs/libgimpbase/tmpl/gimprectangle.sgml @@ -17,6 +17,9 @@ gimprectangle + + + diff --git a/devel-docs/libgimpbase/tmpl/gimpsignal.sgml b/devel-docs/libgimpbase/tmpl/gimpsignal.sgml index fff1ea0892..20b55f4e3b 100644 --- a/devel-docs/libgimpbase/tmpl/gimpsignal.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpsignal.sgml @@ -2,32 +2,30 @@ gimpsignal -Portable signal handling. + -Portable signal handling. -signal(2), signal(5 or 7), sigaction(2). + + + + -A prototype for signal handler functions. Note that each function which -takes or returns a variable of this type also accepts or may return -special values defined by your system's signal.h header file (like -@SIG_DFL or @SIG_IGN). + -@signum: The number of the signal. Useful if different signals are handled - by a single handler. +@signum: diff --git a/devel-docs/libgimpbase/tmpl/gimpunit.sgml b/devel-docs/libgimpbase/tmpl/gimpunit.sgml index 6113e2546c..d4ff88e9f3 100644 --- a/devel-docs/libgimpbase/tmpl/gimpunit.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpunit.sgml @@ -2,27 +2,24 @@ gimpunit -Provides a collection of predefined units and functions for creating -user-defined units. + -Provides a collection of predefined units and functions for creating -user-defined units. -#GimpUnitMenu - - -#GimpSizeEntry + + + + @@ -41,6 +38,7 @@ user-defined units. +@void: @Returns: @@ -49,6 +47,7 @@ user-defined units. +@void: @Returns: @@ -148,9 +147,31 @@ user-defined units. @Returns: + + + + + +@pixels: +@unit: +@resolution: +@Returns: + + + + + + + +@value: +@unit: +@resolution: +@Returns: + + -#GIMP_TYPE_UNIT is a #GType derived from #G_TYPE_INT. + diff --git a/devel-docs/libgimpbase/tmpl/gimputils.sgml b/devel-docs/libgimpbase/tmpl/gimputils.sgml index a31a99d311..c734837069 100644 --- a/devel-docs/libgimpbase/tmpl/gimputils.sgml +++ b/devel-docs/libgimpbase/tmpl/gimputils.sgml @@ -2,7 +2,7 @@ gimputils -Utilities of general interest + @@ -17,6 +17,9 @@ Utilities of general interest + + + diff --git a/devel-docs/libgimpbase/tmpl/gimpversion.sgml b/devel-docs/libgimpbase/tmpl/gimpversion.sgml index c3fdf42a67..4a4eece16f 100644 --- a/devel-docs/libgimpbase/tmpl/gimpversion.sgml +++ b/devel-docs/libgimpbase/tmpl/gimpversion.sgml @@ -2,13 +2,10 @@ gimpversion -Macros and constants useful for determining GIMP's version number and -capabilities. + -Macros and constants useful for determining GIMP's version number and -capabilities. @@ -20,6 +17,9 @@ capabilities. + + + @@ -50,7 +50,7 @@ capabilities. -Since: GIMP 2.2 + diff --git a/libgimpbase/gimpbaseenums.h b/libgimpbase/gimpbaseenums.h index f4a4d64081..3ad47b85d8 100644 --- a/libgimpbase/gimpbaseenums.h +++ b/libgimpbase/gimpbaseenums.h @@ -20,6 +20,15 @@ #define __GIMP_BASE_ENUMS_H__ +/** + * SECTION: gimpbaseenums + * @title: gimpbaseenums + * @short_description: Basic GIMP enumeration data types. + * + * Basic GIMP enumeration data types. + **/ + + G_BEGIN_DECLS /* For information look into the C source or the html documentation */ diff --git a/libgimpbase/gimpbasetypes.c b/libgimpbase/gimpbasetypes.c index fa5b7de919..e9dfb3e767 100644 --- a/libgimpbase/gimpbasetypes.c +++ b/libgimpbase/gimpbasetypes.c @@ -26,6 +26,17 @@ #include "gimpbasetypes.h" +/** + * SECTION: gimpbasetypes + * @title: gimpbasetypes + * @short_description: Translation between gettext translation domain + * identifier and GType. + * + * Translation between gettext translation domain identifier and + * GType. + **/ + + static GQuark gimp_translation_domain_quark (void) G_GNUC_CONST; static GQuark gimp_translation_context_quark (void) G_GNUC_CONST; static GQuark gimp_value_descriptions_quark (void) G_GNUC_CONST; @@ -38,7 +49,7 @@ static GQuark gimp_value_descriptions_quark (void) G_GNUC_CONST; * * This function attaches a constant string as a gettext translation * domain identifier to a #GType. The only purpose of this function is - * to use it when registering a #GTypeEnum with translatable value + * to use it when registering a #G_TYPE_ENUM with translatable value * names. * * Since: GIMP 2.2 @@ -58,7 +69,7 @@ gimp_type_set_translation_domain (GType type, * Retrieves the gettext translation domain identifier that has been * previously set using gimp_type_set_translation_domain(). You should * not need to use this function directly, use gimp_enum_get_value() - * or gimp_enum_value_get_name() instead. + * or gimp_enum_value_get_desc() instead. * * Return value: the translation domain associated with @type * or %NULL if no domain was set @@ -74,12 +85,12 @@ gimp_type_get_translation_domain (GType type) /** * gimp_type_set_translation_context: - * @type: a #GType - * @domain: a constant string that identifies a translation context or %NULL + * @type: a #GType + * @context: a constant string that identifies a translation context or %NULL * * This function attaches a constant string as a translation context * to a #GType. The only purpose of this function is to use it when - * registering a #GTypeEnum with translatable value names. + * registering a #G_TYPE_ENUM with translatable value names. * * Since: GIMP 2.8 **/ @@ -98,7 +109,7 @@ gimp_type_set_translation_context (GType type, * Retrieves the translation context that has been previously set * using gimp_type_set_translation_context(). You should not need to * use this function directly, use gimp_enum_get_value() or - * gimp_enum_value_get_name() instead. + * gimp_enum_value_get_desc() instead. * * Return value: the translation context associated with @type * or %NULL if no context was set diff --git a/libgimpbase/gimpbasetypes.h b/libgimpbase/gimpbasetypes.h index 7fe3ce77ca..e53a6dfd21 100644 --- a/libgimpbase/gimpbasetypes.h +++ b/libgimpbase/gimpbasetypes.h @@ -42,6 +42,15 @@ typedef void (* GimpDatafileLoaderFunc) (const GimpDatafileData *file_data, gpointer user_data); +/** + * GimpEnumDesc: + * @value: An enum value. + * @value_desc: The value's description. + * @value_help: The value's help text. + * + * This structure is used to register translatable descriptions and + * help texts for enum values. See gimp_enum_set_value_descriptions(). + **/ struct _GimpEnumDesc { gint value; @@ -49,6 +58,15 @@ struct _GimpEnumDesc const gchar *value_help; }; +/** + * GimpFlagsDesc: + * @value: A flag value. + * @value_desc: The value's description. + * @value_help: The value's help text. + * + * This structure is used to register translatable descriptions and + * help texts for flag values. See gimp_flags_set_value_descriptions(). + **/ struct _GimpFlagsDesc { guint value; diff --git a/libgimpbase/gimpchecks.c b/libgimpbase/gimpchecks.c index 18aa9796a8..4f5ac5eadb 100644 --- a/libgimpbase/gimpchecks.c +++ b/libgimpbase/gimpchecks.c @@ -28,6 +28,16 @@ #include "gimpchecks.h" +/** + * SECTION: gimpchecks + * @title: gimpchecks + * @short_description: Constants and functions related to rendering + * checkerboards. + * + * Constants and functions related to rendering checkerboards. + **/ + + /** * gimp_checks_get_shades: * @type: the checkerboard type diff --git a/libgimpbase/gimpchecks.h b/libgimpbase/gimpchecks.h index 57bdfddf84..163f69dd52 100644 --- a/libgimpbase/gimpchecks.h +++ b/libgimpbase/gimpchecks.h @@ -22,15 +22,36 @@ G_BEGIN_DECLS -/* the default size of the checks which indicate transparency ... - */ -#define GIMP_CHECK_SIZE 8 -#define GIMP_CHECK_SIZE_SM 4 +/** + * GIMP_CHECK_SIZE: + * + * The default checkerboard size in pixels. This is configurable in + * the core but GIMP plug-ins can't access the user preference and + * should use this constant instead. + **/ +#define GIMP_CHECK_SIZE 8 -/* ... and their default shades - */ -#define GIMP_CHECK_DARK 0.4 -#define GIMP_CHECK_LIGHT 0.6 +/** + * GIMP_CHECK_SIZE_SM: + * + * The default small checkerboard size in pixels. + **/ +#define GIMP_CHECK_SIZE_SM 4 + + +/** + * GIMP_CHECK_DARK: + * + * The dark gray value for the default checkerboard pattern. + **/ +#define GIMP_CHECK_DARK 0.4 + +/** + * GIMP_CHECK_LIGHT: + * + * The dark light value for the default checkerboard pattern. + **/ +#define GIMP_CHECK_LIGHT 0.6 void gimp_checks_get_shades (GimpCheckType type, diff --git a/libgimpbase/gimpcpuaccel.c b/libgimpbase/gimpcpuaccel.c index a810f1603c..3162f58658 100644 --- a/libgimpbase/gimpcpuaccel.c +++ b/libgimpbase/gimpcpuaccel.c @@ -38,6 +38,15 @@ #include "gimpcpuaccel.h" +/** + * SECTION: gimpcpuaccel + * @title: gimpcpuaccel + * @short_description: Functions to query and configure CPU acceleration. + * + * Functions to query and configure CPU acceleration. + **/ + + static GimpCpuAccelFlags cpu_accel (void) G_GNUC_CONST; diff --git a/libgimpbase/gimpdatafiles.c b/libgimpbase/gimpdatafiles.c index ce93577a9f..117b1c89c3 100644 --- a/libgimpbase/gimpdatafiles.c +++ b/libgimpbase/gimpdatafiles.c @@ -42,6 +42,15 @@ #include "gimpenv.h" +/** + * SECTION: gimpdatafiles + * @title: gimpdatafiles + * @short_description: Functions to handle GIMP data files. + * + * Functions to handle GIMP data files. + **/ + + static inline gboolean is_script (const gchar *filename); static inline gboolean is_hidden (const gchar *filename); diff --git a/libgimpbase/gimpdatafiles.h b/libgimpbase/gimpdatafiles.h index 7779b852c6..9a03daced1 100644 --- a/libgimpbase/gimpdatafiles.h +++ b/libgimpbase/gimpdatafiles.h @@ -27,6 +27,19 @@ G_BEGIN_DECLS +/** + * GimpDatafileData: + * @filename: the data file's full path. + * @dirname: the folder the data file is is. + * @basename: the data file's basename. + * @atime: the last time the file was accessed for reading. + * @mtime: the last time the file was modified. + * @ctime: the time the file was created. + * + * This structure is passed to the #GimpDatafileLoaderFunc given to + * gimp_datafiles_read_directories() for each file encountered in the + * data path. + **/ struct _GimpDatafileData { const gchar *filename; diff --git a/libgimpbase/gimpenv.c b/libgimpbase/gimpenv.c index bdbfda0e5f..4bc5f7e769 100644 --- a/libgimpbase/gimpenv.c +++ b/libgimpbase/gimpenv.c @@ -65,6 +65,16 @@ #endif +/** + * SECTION: gimpenv + * @title: gimpenv + * @short_description: Functions to access the GIMP environment. + * + * A set of functions to find the locations of GIMP's data directories + * and configuration files. + **/ + + static gchar * gimp_env_get_dir (const gchar *gimp_env_name, const gchar *env_dir); diff --git a/libgimpbase/gimplimits.h b/libgimpbase/gimplimits.h index f644bf4dcc..1bfd43da1f 100644 --- a/libgimpbase/gimplimits.h +++ b/libgimpbase/gimplimits.h @@ -25,18 +25,63 @@ G_BEGIN_DECLS -/* pixel sizes - */ +/** + * SECTION: gimplimits + * @title: gimplimits + * @short_description: Boundaries of some GIMP data types and some + * global constants. + * + * Boundaries of some GIMP data types and some global constants. + **/ + + +/** + * GIMP_MIN_IMAGE_SIZE: + * + * The minimum width and height of a GIMP image in pixels. + **/ #define GIMP_MIN_IMAGE_SIZE 1 + +/** + * GIMP_MAX_IMAGE_SIZE: + * + * The maximum width and height of a GIMP image in pixels. This is a + * somewhat arbitray value that can be used when an upper value for + * pixel sizes is needed; for example to give a spin button an upper + * limit. + **/ #define GIMP_MAX_IMAGE_SIZE 262144 /* 2^18 */ -/* dots per inch - */ + +/** + * GIMP_MIN_RESOLUTION: + * + * The minimum resolution of a GIMP image in pixels per inch. This is + * a somewhat arbitray value that can be used when a lower value for a + * resolution is needed. GIMP will not accept resolutions smaller than + * this value. + **/ #define GIMP_MIN_RESOLUTION 5e-3 /* shouldn't display as 0.000 */ + +/** + * GIMP_MAX_RESOLUTION: + * + * The maximum resolution of a GIMP image in pixels per inch. This is + * a somewhat arbitray value that can be used to when an upper value + * for a resolution is needed. GIMP will not accept resolutions larger + * than this value. + **/ #define GIMP_MAX_RESOLUTION 65536.0 -/* memory sizes - */ + +/** + * GIMP_MAX_MEMSIZE: + * + * A large but arbitrary value that can be used when an upper limit + * for a memory size (in bytes) is needed. It is smaller than + * %G_MAXDOUBLE since the #GimpMemsizeEntry doesn't handle larger + * values. + **/ #define GIMP_MAX_MEMSIZE ((guint64) 1 << 42) /* 4 terabyte; * needs a 64bit variable * and must be < G_MAXDOUBLE diff --git a/libgimpbase/gimpmemsize.c b/libgimpbase/gimpmemsize.c index 3be522b81b..2c8118b0af 100644 --- a/libgimpbase/gimpmemsize.c +++ b/libgimpbase/gimpmemsize.c @@ -28,6 +28,15 @@ #include "libgimp/libgimp-intl.h" +/** + * SECTION: gimpmemsize + * @title: gimpmemsize + * @short_description: Functions to (de)serialize a given memory size. + * + * Functions to (de)serialize a given memory size. + **/ + + static void memsize_to_string (const GValue *src_value, GValue *dest_value); static void string_to_memsize (const GValue *src_value, diff --git a/libgimpbase/gimpmemsize.h b/libgimpbase/gimpmemsize.h index 7611e8b2c0..c61454390e 100644 --- a/libgimpbase/gimpmemsize.h +++ b/libgimpbase/gimpmemsize.h @@ -22,9 +22,11 @@ G_BEGIN_DECLS -/* - * GIMP_TYPE_MEMSIZE - */ +/** + * GIMP_TYPE_MEMSIZE: + * + * #GIMP_TYPE_MEMSIZE is a #GType derived from #G_TYPE_UINT64. + **/ #define GIMP_TYPE_MEMSIZE (gimp_memsize_get_type ()) #define GIMP_VALUE_HOLDS_MEMSIZE(value) (G_TYPE_CHECK_VALUE_TYPE ((value), GIMP_TYPE_MEMSIZE)) diff --git a/libgimpbase/gimpparam.h b/libgimpbase/gimpparam.h index e5926d9f7e..6b5054b9d3 100644 --- a/libgimpbase/gimpparam.h +++ b/libgimpbase/gimpparam.h @@ -19,16 +19,46 @@ #ifndef __GIMP_PARAM_H__ #define __GIMP_PARAM_H__ -/* For information look into the C source or the html documentation */ + +/** + * SECTION: gimpparam + * @title: gimpparam + * @short_description: Definitions of useful #GParamFlags. + * + * Definitions of useful #GParamFlags. + **/ +/** + * GIMP_PARAM_STATIC_STRINGS: + * + * Since: GIMP 2.4 + **/ #define GIMP_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | \ G_PARAM_STATIC_NICK | \ G_PARAM_STATIC_BLURB) + +/** + * GIMP_PARAM_READABLE: + * + * Since: GIMP 2.4 + **/ #define GIMP_PARAM_READABLE (G_PARAM_READABLE | \ GIMP_PARAM_STATIC_STRINGS) + +/** + * GIMP_PARAM_WRITABLE: + * + * Since: GIMP 2.4 + **/ #define GIMP_PARAM_WRITABLE (G_PARAM_WRITABLE | \ GIMP_PARAM_STATIC_STRINGS) + +/** + * GIMP_PARAM_READWRITE: + * + * Since: GIMP 2.4 + **/ #define GIMP_PARAM_READWRITE (G_PARAM_READWRITE | \ GIMP_PARAM_STATIC_STRINGS) diff --git a/libgimpbase/gimpparasite.c b/libgimpbase/gimpparasite.c index 153b2f4823..d8ab67d776 100644 --- a/libgimpbase/gimpparasite.c +++ b/libgimpbase/gimpparasite.c @@ -38,6 +38,19 @@ #include "gimpparasite.h" +/** + * SECTION: gimpparasite + * @title: gimpparasite + * @short_description: Arbitrary pieces of data which can be attached + * to various GIMP objects. + * @see_also: gimp_image_parasite_attach(), + * gimp_drawable_parasite_attach(), gimp_parasite_attach() + * and their related functions. + * + * Arbitrary pieces of data which can be attached to various GIMP objects. + **/ + + /* * GIMP_TYPE_PARASITE */ diff --git a/libgimpbase/gimpparasiteio.c b/libgimpbase/gimpparasiteio.c index 1fbb511430..b601a9de8f 100644 --- a/libgimpbase/gimpparasiteio.c +++ b/libgimpbase/gimpparasiteio.c @@ -35,6 +35,18 @@ #include "gimpparasiteio.h" +/** + * SECTION: gimpparasiteio + * @title: gimpparasiteio + * @short_description: Utility functions to (de)serialize certain C + * structures to/from #GimpParasite's. + * @see_also: #GimpParasite + * + * Utility functions to (de)serialize certain C structures to/from* + * #GimpParasite's. + **/ + + void gimp_pixpipe_params_init (GimpPixPipeParams *params) { diff --git a/libgimpbase/gimpparasiteio.h b/libgimpbase/gimpparasiteio.h index 9a8a8df94b..ca4ebe4881 100644 --- a/libgimpbase/gimpparasiteio.h +++ b/libgimpbase/gimpparasiteio.h @@ -38,7 +38,9 @@ G_BEGIN_DECLS #define GIMP_PIXPIPE_MAXDIM 4 -typedef struct +typedef struct _GimpPixPipeParams GimpPixPipeParams; + +struct _GimpPixPipeParams { gint step; gint ncells; @@ -52,7 +54,7 @@ typedef struct gint rank[GIMP_PIXPIPE_MAXDIM]; gchar *selection[GIMP_PIXPIPE_MAXDIM]; gboolean free_selection_string; -} GimpPixPipeParams; +}; /* Initalize with dummy values */ void gimp_pixpipe_params_init (GimpPixPipeParams *params); diff --git a/libgimpbase/gimprectangle.c b/libgimpbase/gimprectangle.c index df44d6497f..2f7e917f22 100644 --- a/libgimpbase/gimprectangle.c +++ b/libgimpbase/gimprectangle.c @@ -25,6 +25,15 @@ #include "gimprectangle.h" +/** + * SECTION: gimprectangle + * @title: gimprectangle + * @short_description: Utility functions dealing with rectangle extents. + * + * Utility functions dealing with rectangle extents. + **/ + + /** * gimp_rectangle_intersect: * @x1: origin of first rectangle diff --git a/libgimpbase/gimpsignal.c b/libgimpbase/gimpsignal.c index edcd90cbe2..a773bae533 100644 --- a/libgimpbase/gimpsignal.c +++ b/libgimpbase/gimpsignal.c @@ -27,6 +27,16 @@ #include "gimpsignal.h" +/** + * SECTION: gimpsignal + * @title: gimpsignal + * @short_description: Portable signal handling. + * @see_also: signal(2), signal(5 or 7), sigaction(2). + * + * Portable signal handling. + **/ + + /* Courtesy of Austin Donnelly 06-04-2000 to address bug #2742 */ /** diff --git a/libgimpbase/gimpsignal.h b/libgimpbase/gimpsignal.h index 8682f3dc05..031e2c34d1 100644 --- a/libgimpbase/gimpsignal.h +++ b/libgimpbase/gimpsignal.h @@ -26,10 +26,16 @@ G_BEGIN_DECLS /* For information look into the C source or the html documentation */ -/* GimpSignalHandlerFunc is a reference to a (signal handler) function - * that takes a signal ID and returns void. - * signal(2) returns such references; so does gimp_signal_private. - */ +/** + * GimpSignalHandlerFunc: + * @signum: The number of the signal. Useful if different signals are + * handled by a single handler. + * + * A prototype for a reference to a signal handler functions. Note + * that each function which takes or returns a variable of this type + * also accepts or may return special values defined by your system's + * signal.h header file (like @SIG_DFL or @SIG_IGN). + **/ typedef void (* GimpSignalHandlerFunc) (gint signum); GimpSignalHandlerFunc gimp_signal_private (gint signum, diff --git a/libgimpbase/gimpunit.c b/libgimpbase/gimpunit.c index 006f3f2f83..def23ba472 100644 --- a/libgimpbase/gimpunit.c +++ b/libgimpbase/gimpunit.c @@ -31,6 +31,18 @@ #include "gimpunit.h" +/** + * SECTION: gimpunit + * @title: gimpunit + * @short_description: Provides a collection of predefined units and + * functions for creating user-defined units. + * @see_also: #GimpUnitMenu, #GimpSizeEntry. + * + * Provides a collection of predefined units and functions for + * creating user-defined units. + **/ + + static void unit_to_string (const GValue *src_value, GValue *dest_value); static void string_to_unit (const GValue *src_value, @@ -465,7 +477,9 @@ gimp_param_spec_unit (const gchar *name, * @unit: unit to convert to * @resolution: resloution in DPI * - * Returns: %pixels converted to units. + * Converts a @value specified in pixels to @unit. + * + * Returns: @pixels converted to units. * * Since: GIMP 2.8 **/ @@ -483,10 +497,12 @@ gimp_pixels_to_units (gdouble pixels, /** * gimp_units_to_pixels: * @value: value in units - * @unit: unit of %value + * @unit: unit of @value * @resolution: resloution in DPI * - * Returns: %value converted to pixels. + * Converts a @value specified in @unit to pixels. + * + * Returns: @value converted to pixels. * * Since: GIMP 2.8 **/ diff --git a/libgimpbase/gimpunit.h b/libgimpbase/gimpunit.h index 00c9749283..448d0419ff 100644 --- a/libgimpbase/gimpunit.h +++ b/libgimpbase/gimpunit.h @@ -26,9 +26,11 @@ G_BEGIN_DECLS /* For information look into the C source or the html documentation */ -/* - * GIMP_TYPE_UNIT - */ +/** + * GIMP_TYPE_UNIT: + * + * #GIMP_TYPE_UNIT is a #GType derived from #G_TYPE_INT. + **/ #define GIMP_TYPE_UNIT (gimp_unit_get_type ()) #define GIMP_VALUE_HOLDS_UNIT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), GIMP_TYPE_UNIT)) @@ -84,7 +86,7 @@ const gchar * gimp_unit_get_plural (GimpUnit unit); gdouble gimp_pixels_to_units (gdouble pixels, GimpUnit unit, gdouble resolution); -gdouble gimp_units_to_pixels (gdouble units, +gdouble gimp_units_to_pixels (gdouble value, GimpUnit unit, gdouble resolution); diff --git a/libgimpbase/gimputils.c b/libgimpbase/gimputils.c index a64acb726d..b6a7965e82 100644 --- a/libgimpbase/gimputils.c +++ b/libgimpbase/gimputils.c @@ -32,6 +32,15 @@ #include "libgimp/libgimp-intl.h" +/** + * SECTION: gimputils + * @title: gimputils + * @short_description: Utilities of general interest + * + * Utilities of general interest + **/ + + /** * gimp_utf8_strtrim: * @str: an UTF-8 encoded string (or %NULL) @@ -236,7 +245,7 @@ gimp_filename_to_utf8 (const gchar *filename) * In some languages, mnemonics are handled by adding the mnemonic * character in brackets (like "File (_F)"). This function recognizes * this construct and removes the whole bracket construction to get - * rid of the mnemonic (see bug #157561). + * rid of the mnemonic (see bug 157561). * * Return value: A (possibly stripped) copy of @str which should be * freed using g_free() when it is not needed any longer.