APIDOC: IBusObject IBusObservedPath

diff --git a/src/ibusobject.c b/src/ibusobject.c
index 5e7ea58..f50c213 100644 (file)
--- 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().
+     *
+     * <note><para>Argument @user_data is ignored in this function.</para></note>
+     */
     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 (file)
--- 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 (file)
--- 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:
+ * &lt;path mtime="<i>modified time</i>" &gt;<i>path</i>&lt;/path&gt;
+ */
 void                 ibus_observed_path_output              (IBusObservedPath   *path,
                                                              GString            *output,
                                                              gint                indent);