From fcc0a5a42471ab8cd8682e034edb7fc94410d9f0 Mon Sep 17 00:00:00 2001 From: Michael Natterer Date: Tue, 29 Jun 2010 22:35:34 +0200 Subject: [PATCH] libgimpmodule: move docs from templates to inline comments --- devel-docs/libgimpmodule/.gitignore | 1 + devel-docs/libgimpmodule/tmpl/.gitignore | 2 - devel-docs/libgimpmodule/tmpl/gimpmodule.sgml | 217 ------------------ .../libgimpmodule/tmpl/gimpmoduledb.sgml | 94 -------- libgimpmodule/gimpmodule.c | 11 + libgimpmodule/gimpmodule.h | 100 ++++++-- libgimpmodule/gimpmoduledb.c | 10 + 7 files changed, 107 insertions(+), 328 deletions(-) delete mode 100644 devel-docs/libgimpmodule/tmpl/.gitignore delete mode 100644 devel-docs/libgimpmodule/tmpl/gimpmodule.sgml delete mode 100644 devel-docs/libgimpmodule/tmpl/gimpmoduledb.sgml diff --git a/devel-docs/libgimpmodule/.gitignore b/devel-docs/libgimpmodule/.gitignore index ae20e0938f..81066e01d3 100644 --- a/devel-docs/libgimpmodule/.gitignore +++ b/devel-docs/libgimpmodule/.gitignore @@ -12,6 +12,7 @@ /libgimpmodule-undeclared.txt /libgimpmodule-undocumented.txt /html +/tmpl /xml /version /.libs diff --git a/devel-docs/libgimpmodule/tmpl/.gitignore b/devel-docs/libgimpmodule/tmpl/.gitignore deleted file mode 100644 index 09abfee65e..0000000000 --- a/devel-docs/libgimpmodule/tmpl/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -/libgimpmodule-unused.sgml -/*.bak diff --git a/devel-docs/libgimpmodule/tmpl/gimpmodule.sgml b/devel-docs/libgimpmodule/tmpl/gimpmodule.sgml deleted file mode 100644 index f39e6d9e66..0000000000 --- a/devel-docs/libgimpmodule/tmpl/gimpmodule.sgml +++ /dev/null @@ -1,217 +0,0 @@ - -GimpModule - - -A #GTypeModule subclass which implements module loading using #GModule. - - - -A #GTypeModule subclass which implements module loading using #GModule. - - - - -#GModule - - -#GTypeModule - - - - - - - -#GimpModule is a generic mechanism to dynamically load modules into -GIMP. It is a #GTypeModule subclass, implementing module loading -using #GModule. #GimpModule does not know which functionality is -implemented by the modules, it just provides a framework to get -arbitrary #GType implementations loaded from disk. - - -@filename: -@verbose: -@state: -@on_disk: -@load_inhibit: -@info: -@last_module_error: - - - - - - -@gimpmodule: the object which received the signal. - - - -This structure contains information about a loadable module. - - -@abi_version: The #GIMP_MODULE_ABI_VERSION the module was compiled against. -@purpose: The module's general purpose. -@author: The module's author. -@version: The module's version. -@copyright: The module's copyright. -@date: The module's release date. - - - -The possible states a #GimpModule can be in. - - -@GIMP_MODULE_STATE_ERROR: Missing gimp_module_register() function - or other error. -@GIMP_MODULE_STATE_LOADED: An instance of a type implemented by - this module is allocated. -@GIMP_MODULE_STATE_LOAD_FAILED: gimp_module_register() returned #FALSE. -@GIMP_MODULE_STATE_NOT_LOADED: There are no instances allocated of - types implemented by this module. - - - -The signature of the query function a loadable GIMP module must -implement. In the module, the function must be called -gimp_module_query(). - - - -#GimpModule will copy the returned #GimpModuleInfo struct, so the -module doesn't need to keep these values around (however in most cases -the module will just return a pointer to a constant structure). - - -@module: The #GimpModule responsible for this loadable module. -@Returns: The #GimpModuleInfo struct describing the module. - - - - -The signature of the register function a loadable GIMP module must -implement. In the module, the function must be called -gimp_module_register(). - - - -When this function is called, the module should register all the types -it implements with the passed @module. - - -@module: The #GimpModule responsible for this loadable module. -@Returns: #TRUE on success, #FALSE otherwise. - - - - -The version of the module system's ABI. Modules put this value into -#GimpModuleInfo's @abi_version field so the code loading the modules -can check if it was compiled against the same module ABI the modules -are compiled against. - - - - - - - - - - - - - - - - -@filename: -@load_inhibit: -@verbose: -@Returns: - - - - - - - -@module: - - - - - - - -@module: -@Returns: - - - - - - - -@module: -@load_inhibit: - - - - - - - -@state: -@Returns: - - - - - - - -@module: -@name: -@const_static_values: -@Returns: - - - - - - - -@abi_version: -@purpose: -@author: -@version: -@copyright: -@date: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: - - - - - - - -@Returns: - - diff --git a/devel-docs/libgimpmodule/tmpl/gimpmoduledb.sgml b/devel-docs/libgimpmodule/tmpl/gimpmoduledb.sgml deleted file mode 100644 index 68a4db6115..0000000000 --- a/devel-docs/libgimpmodule/tmpl/gimpmoduledb.sgml +++ /dev/null @@ -1,94 +0,0 @@ - -GimpModuleDB - - -Keeps a list of #GimpModule's found in a given searchpath. - - - -Keeps a list of #GimpModule's found in a given searchpath. - - - - - - - - - - - - -The #GimpModuleDB struct contains no public members. - - - - - - - - -@gimpmoduledb: the object which received the signal. -@arg1: - - - - - - -@gimpmoduledb: the object which received the signal. -@arg1: - - - - - - -@gimpmoduledb: the object which received the signal. -@arg1: - - - - - - -@verbose: -@Returns: - - - - - - - -@db: -@load_inhibit: - - - - - - - -@db: -@Returns: - - - - - - - -@db: -@module_path: - - - - - - - -@db: -@module_path: - - diff --git a/libgimpmodule/gimpmodule.c b/libgimpmodule/gimpmodule.c index 17d01d305e..f8c2b9a197 100644 --- a/libgimpmodule/gimpmodule.c +++ b/libgimpmodule/gimpmodule.c @@ -33,6 +33,17 @@ #include "libgimp/libgimp-intl.h" +/** + * SECTION: gimpmodule + * @title: GimpModule + * @short_description: A #GTypeModule subclass which implements module + * loading using #GModule. + * @see_also: #GModule, #GTypeModule + * + * A #GTypeModule subclass which implements module loading using #GModule. + **/ + + enum { MODIFIED, diff --git a/libgimpmodule/gimpmodule.h b/libgimpmodule/gimpmodule.h index 7aee0982c2..bf6b9b9352 100644 --- a/libgimpmodule/gimpmodule.h +++ b/libgimpmodule/gimpmodule.h @@ -31,28 +31,43 @@ G_BEGIN_DECLS -/* increment the ABI version each time one of the following changes: +/** + * GIMP_MODULE_ABI_VERSION: + * + * The version of the module system's ABI. Modules put this value into + * #GimpModuleInfo's @abi_version field so the code loading the modules + * can check if it was compiled against the same module ABI the modules + * are compiled against. + * + * GIMP_MODULE_ABI_VERSION is incremented each time one of the + * following changes: * * - the libgimpmodule implementation (if the change affects modules). - * - one of the classes implemented by modules (currently GimpColorDisplay, - * GimpColorSelector and GimpController). - */ + * + * - one of the classes implemented by modules (currently #GimpColorDisplay, + * #GimpColorSelector and #GimpController). + **/ #define GIMP_MODULE_ABI_VERSION 0x0004 +/** + * GimpModuleState: + * @GIMP_MODULE_STATE_ERROR: Missing gimp_module_register() function + * or other error. + * @GIMP_MODULE_STATE_LOADED: An instance of a type implemented by + * this module is allocated. + * @GIMP_MODULE_STATE_LOAD_FAILED: gimp_module_register() returned %FALSE. + * @GIMP_MODULE_STATE_NOT_LOADED: There are no instances allocated of + * types implemented by this module. + * + * The possible states a #GimpModule can be in. + **/ typedef enum { - GIMP_MODULE_STATE_ERROR, /* missing gimp_module_register function - * or other error - */ - GIMP_MODULE_STATE_LOADED, /* an instance of a type implemented by - * this module is allocated - */ - GIMP_MODULE_STATE_LOAD_FAILED, /* gimp_module_register returned FALSE - */ - GIMP_MODULE_STATE_NOT_LOADED /* there are no instances allocated of - * types implemented by this module - */ + GIMP_MODULE_STATE_ERROR, + GIMP_MODULE_STATE_LOADED, + GIMP_MODULE_STATE_LOAD_FAILED, + GIMP_MODULE_STATE_NOT_LOADED } GimpModuleState; @@ -66,6 +81,17 @@ typedef enum } GimpModuleError; +/** + * GimpModuleInfo: + * @abi_version: The #GIMP_MODULE_ABI_VERSION the module was compiled against. + * @purpose: The module's general purpose. + * @author: The module's author. + * @version: The module's version. + * @copyright: The module's copyright. + * @date: The module's release date. + * + * This structure contains information about a loadable module. + **/ struct _GimpModuleInfo { guint32 abi_version; @@ -77,9 +103,37 @@ struct _GimpModuleInfo }; +/** + * GimpModuleQueryFunc: + * @module: The #GimpModule responsible for this loadable module. + * @Returns: The #GimpModuleInfo struct describing the module. + * + * The signature of the query function a loadable GIMP module must + * implement. In the module, the function must be called + * gimp_module_query(). + * + * #GimpModule will copy the returned #GimpModuleInfo struct, so the + * module doesn't need to keep these values around (however in most + * cases the module will just return a pointer to a constant + * structure). + **/ typedef const GimpModuleInfo * (* GimpModuleQueryFunc) (GTypeModule *module); + +/** + * GimpModuleRegisterFunc: + * @module: The #GimpModule responsible for this loadable module. + * @Returns: %TRUE on success, %FALSE otherwise. + * + * The signature of the register function a loadable GIMP module must + * implement. In the module, the function must be called + * gimp_module_register(). + * + * When this function is called, the module should register all the types + * it implements with the passed @module. + **/ typedef gboolean (* GimpModuleRegisterFunc) (GTypeModule *module); + /* GimpModules have to implement these */ G_MODULE_EXPORT const GimpModuleInfo * gimp_module_query (GTypeModule *module); G_MODULE_EXPORT gboolean gimp_module_register (GTypeModule *module); @@ -95,6 +149,22 @@ G_MODULE_EXPORT gboolean gimp_module_register (GTypeModule *module typedef struct _GimpModuleClass GimpModuleClass; +/** + * GimpModule: + * @filename: + * @verbose: + * @state: + * @on_disk: + * @load_inhibit: + * @info: + * @last_module_error: + * + * #GimpModule is a generic mechanism to dynamically load modules into + * GIMP. It is a #GTypeModule subclass, implementing module loading + * using #GModule. #GimpModule does not know which functionality is + * implemented by the modules, it just provides a framework to get + * arbitrary #GType implementations loaded from disk. + **/ struct _GimpModule { GTypeModule parent_instance; diff --git a/libgimpmodule/gimpmoduledb.c b/libgimpmodule/gimpmoduledb.c index 14646fe2dd..071895d7de 100644 --- a/libgimpmodule/gimpmoduledb.c +++ b/libgimpmodule/gimpmoduledb.c @@ -30,6 +30,16 @@ #include "gimpmoduledb.h" +/** + * SECTION: gimpmoduledb + * @title: GimpModuleDB + * @short_description: Keeps a list of #GimpModule's found in a given + * searchpath. + * + * Keeps a list of #GimpModule's found in a given searchpath. + **/ + + enum { ADD,