From f2452bfeedf06b4548b3d905a18e3147358eb13a Mon Sep 17 00:00:00 2001 From: Ding-Yi Chen Date: Mon, 3 Aug 2009 18:06:06 +1000 Subject: [PATCH] APIDOC: IBusObject IBusObservedPath --- src/ibusobject.c | 21 ++++++++--------- src/ibusobject.h | 23 ++++++++++++++++-- src/ibusobservedpath.h | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 95 insertions(+), 13 deletions(-) diff --git a/src/ibusobject.c b/src/ibusobject.c index 5e7ea58..f50c213 100644 --- a/src/ibusobject.c +++ b/src/ibusobject.c @@ -112,6 +112,16 @@ ibus_object_class_init (IBusObjectClass *klass) klass->destroy = ibus_object_real_destroy; /* install signals */ + /** + * IBusObject::destroy: + * @object: An IBusObject. + * + * Destroy and free an IBusObject + * + * See also: ibus_object_destroy(). + * + * Argument @user_data is ignored in this function. + */ object_signals[DESTROY] = g_signal_new (I_("destroy"), G_TYPE_FROM_CLASS (gobject_class), @@ -198,17 +208,6 @@ ibus_object_real_destroy (IBusObject *obj) g_signal_handlers_destroy (obj); } -/** - * ibus_object_destroy: - * @object: an #IBusObject to destroy. - * - * Emit the "destory" signal notifying all reference holders that they should - * release the #IBusObject. - * - * The memory for the object itself won't be deleted until its reference count - * actually drops to 0; ibus_object_destroy merely asks reference holders to - * release their references. it does not free the object. - */ void ibus_object_destroy (IBusObject *obj) { diff --git a/src/ibusobject.h b/src/ibusobject.h index 0b7066b..987f66e 100644 --- a/src/ibusobject.h +++ b/src/ibusobject.h @@ -19,10 +19,10 @@ */ /** * SECTION: ibusobject - * @short_description: Base Object of IBus. + * @short_description: Base object of IBus. * @stability: Stable * - * IBus Object is the base object for all objects in IBus. + * IBusObject is the base object for all objects in IBus. */ #ifndef __IBUS_OBJECT_H_ #define __IBUS_OBJECT_H_ @@ -100,7 +100,26 @@ struct _IBusObjectClass { }; GType ibus_object_get_type (void); + +/** + * ibus_object_new: + * @returns: A newly allocated IBusObject + * + * New an IBusObject. + */ IBusObject *ibus_object_new (void); + +/** + * ibus_object_destroy: + * @object: an #IBusObject to destroy. + * + * Emit the "destory" signal notifying all reference holders that they should + * release the #IBusObject. + * + * The memory for the object itself won't be deleted until its reference count + * actually drops to 0; ibus_object_destroy merely asks reference holders to + * release their references. It does not free the object. + */ void ibus_object_destroy (IBusObject *object); G_END_DECLS diff --git a/src/ibusobservedpath.h b/src/ibusobservedpath.h index 4ebd625..eb2c6c1 100644 --- a/src/ibusobservedpath.h +++ b/src/ibusobservedpath.h @@ -17,6 +17,15 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibusobservedpath + * @short_description: Path object of IBus. + * @stability: Stable + * + * IBusObservedPath provides methods for file path manipulation, + * such as monitor modification, directory tree traversal. + */ + #ifndef __IBUS_OBSERVED_PATH_H_ #define __IBUS_OBSERVED_PATH_H_ @@ -46,6 +55,15 @@ G_BEGIN_DECLS typedef struct _IBusObservedPath IBusObservedPath; typedef struct _IBusObservedPathClass IBusObservedPathClass; +/** + * IBusObservedPath: + * @path: Path to be handled. + * @mtime: Modified time. + * @is_dir: Whether the file is the path directory. + * @is_exist: Whether the file exists. + * + * Data structure of IBusObservedPath. + */ struct _IBusObservedPath { IBusSerializable parent; /* instance members */ @@ -64,12 +82,58 @@ struct _IBusObservedPathClass { }; GType ibus_observed_path_get_type (void); + +/** + * ibus_observed_path_new_from_xml_node: + * @node: An XML node that contain path. + * @fill_stat: Auto-fill the path status. + * @returns: A newly allocated IBusObservedPath. + * + * New an IBusObservedPath from an XML node. + */ IBusObservedPath *ibus_observed_path_new_from_xml_node (XMLNode *node, gboolean fill_stat); + +/** + * ibus_observed_path_new: + * @path: The path string. + * @fill_stat: Auto-fill the path status. + * @returns: A newly allocated IBusObservedPath. + * + * New an IBusObservedPath from an XML node. + */ IBusObservedPath *ibus_observed_path_new (const gchar *path, gboolean fill_stat); + +/** + * ibus_observed_path_traverse: + * @path: An IBusObservedPath. + * @returns: A newly allocate GList which holds content in path; NULL if @path is not directory. + * + * Recursively traverse the path and put the files and subdirectory in to a newly allocated + * GLists, if the @path is a directory. Otherwise returns NULL. + */ GList *ibus_observed_path_traverse (IBusObservedPath *path); + +/** + * ibus_observed_path_check_modification: + * @path: An IBusObservedPath. + * @returns: TRUE if mtime is changed; FALSE otherwise. + * + * Checks whether the path is modified by comparing the mtime in object and mtime in file system. + * Returns TRUE if imtime is changed, otherwise FALSE. + */ gboolean ibus_observed_path_check_modification (IBusObservedPath *path); + +/** + * ibus_observed_path_output: + * @path: An IBusObservedPath. + * @output: Path is appended to. + * @indent: number of indent. + * + * Append the observed path to a string with following format: + * <path mtime="modified time" >path</path> + */ void ibus_observed_path_output (IBusObservedPath *path, GString *output, gint indent); -- 2.7.4