GNOME.org
 

[nautilus-actions] Reference manual: Fix NAObjectId documentation

commit a1f6bb77532b8fa02f2b77874a7126f4d46fe10f
Author: Pierre Wieser <pwieser trychlos org>
Date:   Sat Dec 11 16:31:40 2010 +0100

    Reference manual: Fix NAObjectId documentation

 ChangeLog                                    |    8 +++
 docs/reference/nautilus-actions-docs.xml     |    2 +-
 docs/reference/nautilus-actions-sections.txt |   65 +++++++++++++++++--------
 src/api/na-object-id.h                       |   47 +++++++++++-------
 src/api/na-object.h                          |    2 +-
 src/core/na-object-id.c                      |   44 ++++++++++++++---
 6 files changed, 119 insertions(+), 49 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 8d5ed15..2c17587 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2010-12-11 Pierre Wieser <pwieser trychlos org>
 
+	Fix NAObjectId documentation.
+
+	* docs/reference/nautilus-actions-docs.xml:
+	* docs/reference/nautilus-actions-sections.txt:
+	* src/api/na-object-id.h:
+	* src/api/na-object.h:
+	* src/core/na-object-id.c: Updated accordingly.
+
 	Fix NAObject documentation.
 
 	* docs/reference/nautilus-actions-docs.xml
diff --git a/docs/reference/nautilus-actions-docs.xml b/docs/reference/nautilus-actions-docs.xml
index c3cf5de..46f96d5 100644
--- a/docs/reference/nautilus-actions-docs.xml
+++ b/docs/reference/nautilus-actions-docs.xml
@@ -70,7 +70,7 @@
   <chapter>
     <title>NAObject Hierarchy</title>
     <xi:include href="xml/object.xml"/>
-    <xi:include href="xml/na-object-id.xml"/>
+    <xi:include href="xml/object-id.xml"/>
     <xi:include href="xml/na-object-item.xml"/>
     <xi:include href="xml/na-object-action.xml"/>
     <xi:include href="xml/na-object-profile.xml"/>
diff --git a/docs/reference/nautilus-actions-sections.txt b/docs/reference/nautilus-actions-sections.txt
index 01e23c6..44b67c9 100644
--- a/docs/reference/nautilus-actions-sections.txt
+++ b/docs/reference/nautilus-actions-sections.txt
@@ -259,6 +259,7 @@ NAFO_DATA_CAPABILITITES
 </SECTION>
 
 # ---------------------------------------------------------------------
+# NAObject â?? The Deepest Base Class Definition 
 
 <SECTION>
 <FILE>object</FILE>
@@ -291,6 +292,36 @@ NAObjectPrivate
 NAObjectClassPrivate
 </SECTION>
 
+# ---------------------------------------------------------------------
+# NAObjectId â?? The Identified Object Class Definition
+
+<SECTION>
+<FILE>object-id</FILE>
+<TITLE>NAObjectId</TITLE>
+NA_OBJECT_ID_TYPE
+NA_OBJECT_ID
+NA_IS_OBJECT_ID
+NAObjectId
+NAObjectIdClass
+na_object_id_sort_alpha_asc
+na_object_id_sort_alpha_desc
+na_object_id_prepare_for_paste
+na_object_id_set_copy_of_label
+na_object_id_set_new_id
+
+<SUBSECTION Standard>
+na_object_id_get_type
+NA_OBJECT_ID_CLASS
+NA_IS_OBJECT_ID_CLASS
+NA_OBJECT_ID_GET_CLASS
+
+<SUBSECTION Private>
+NAObjectIdPrivate
+NAObjectIdClassPrivate
+</SECTION>
+
+# ---------------------------------------------------------------------
+
 <SECTION>
 <FILE>iduplicable</FILE>
 NA_IDUPLICABLE_TYPE
@@ -315,27 +346,7 @@ NA_IS_IDUPLICABLE
 na_iduplicable_get_type
 </SECTION>
 
-<SECTION>
-<FILE>object-id</FILE>
-<TITLE>NAObjectId</TITLE>
-NA_OBJECT_ID_TYPE
-NAObjectIdPrivate
-NAObjectIdClassPrivate
-NAObjectId
-na_object_id_sort_alpha_asc
-na_object_id_sort_alpha_desc
-na_object_id_prepare_for_paste
-na_object_id_set_copy_of_label
-na_object_id_set_new_id
-
-<SUBSECTION Standard>
-NA_OBJECT_ID
-NA_IS_OBJECT_ID
-na_object_id_get_type
-NA_OBJECT_ID_CLASS
-NA_IS_OBJECT_ID_CLASS
-NA_OBJECT_ID_GET_CLASS
-</SECTION>
+# ---------------------------------------------------------------------
 
 <SECTION>
 <FILE>object-item</FILE>
@@ -367,6 +378,8 @@ NA_IS_OBJECT_ITEM_CLASS
 NA_OBJECT_ITEM_GET_CLASS
 </SECTION>
 
+# ---------------------------------------------------------------------
+
 <SECTION>
 <FILE>object-action</FILE>
 <TITLE>NAObjectAction</TITLE>
@@ -390,6 +403,8 @@ NA_IS_OBJECT_ACTION_CLASS
 NA_OBJECT_ACTION_GET_CLASS
 </SECTION>
 
+# ---------------------------------------------------------------------
+
 <SECTION>
 <FILE>na-object-profile</FILE>
 <TITLE>NAObjectProfile</TITLE>
@@ -410,6 +425,8 @@ NA_IS_OBJECT_PROFILE_CLASS
 NA_OBJECT_PROFILE_GET_CLASS
 </SECTION>
 
+# ---------------------------------------------------------------------
+
 <SECTION>
 <FILE>object-menu</FILE>
 <TITLE>NAObjectMenu</TITLE>
@@ -429,6 +446,8 @@ NA_IS_OBJECT_MENU_CLASS
 NA_OBJECT_MENU_GET_CLASS
 </SECTION>
 
+# ---------------------------------------------------------------------
+
 <SECTION>
 <FILE>icontext</FILE>
 NA_ICONTEXT_TYPE
@@ -451,6 +470,8 @@ NA_IS_ICONTEXT
 na_icontext_get_type
 </SECTION>
 
+# ---------------------------------------------------------------------
+
 <SECTION>
 <FILE>gconf-monitor</FILE>
 <TITLE>NAGConfMonitor</TITLE>
@@ -470,6 +491,8 @@ NA_IS_GCONF_MONITOR_CLASS
 NA_GCONF_MONITOR_GET_CLASS
 </SECTION>
 
+# ---------------------------------------------------------------------
+
 <SECTION>
 <FILE>na-gconf-utils</FILE>
 na_gconf_utils_get_subdirs
diff --git a/src/api/na-object-id.h b/src/api/na-object-id.h
index 8c71ed1..0fb2ae7 100644
--- a/src/api/na-object-id.h
+++ b/src/api/na-object-id.h
@@ -33,12 +33,12 @@
 
 /**
  * SECTION: object-id
- * @title: NAObjectId class definition
- * @short_description: #NAObjectId class definition.
+ * @title: NAObjectId
+ * @short_description: The Identified Object Class Definition
  * @include: nautilus-actions/na-object-id.h
  *
  * This is a pure virtual class, i.e. not an instantiatable one.
- * It serves as the base class for #NAObject-derived object which have
+ * It serves as the base class for #NAObject -derived object which have
  * a unique Id, i.e. for #NAObjectItem and #NAObjectProfile.
  */
 
@@ -46,42 +46,53 @@
 
 G_BEGIN_DECLS
 
-#define NA_OBJECT_ID_TYPE					( na_object_id_get_type())
-#define NA_OBJECT_ID( object )				( G_TYPE_CHECK_INSTANCE_CAST( object, NA_OBJECT_ID_TYPE, NAObjectId ))
-#define NA_OBJECT_ID_CLASS( klass )			( G_TYPE_CHECK_CLASS_CAST( klass, NA_OBJECT_ID_TYPE, NAObjectIdClass ))
-#define NA_IS_OBJECT_ID( object )			( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_OBJECT_ID_TYPE ))
-#define NA_IS_OBJECT_ID_CLASS( klass )		( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_OBJECT_ID_TYPE ))
-#define NA_OBJECT_ID_GET_CLASS( object )	( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_OBJECT_ID_TYPE, NAObjectIdClass ))
+#define NA_OBJECT_ID_TYPE                  ( na_object_id_get_type())
+#define NA_OBJECT_ID( object )             ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_OBJECT_ID_TYPE, NAObjectId ))
+#define NA_OBJECT_ID_CLASS( klass )        ( G_TYPE_CHECK_CLASS_CAST( klass, NA_OBJECT_ID_TYPE, NAObjectIdClass ))
+#define NA_IS_OBJECT_ID( object )          ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_OBJECT_ID_TYPE ))
+#define NA_IS_OBJECT_ID_CLASS( klass )     ( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_OBJECT_ID_TYPE ))
+#define NA_OBJECT_ID_GET_CLASS( object )   ( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_OBJECT_ID_TYPE, NAObjectIdClass ))
 
-typedef struct NAObjectIdPrivate      NAObjectIdPrivate;
+typedef struct _NAObjectIdPrivate      NAObjectIdPrivate;
 
 typedef struct {
+	/*< private >*/
 	NAObject           parent;
 	NAObjectIdPrivate *private;
 }
 	NAObjectId;
 
-typedef struct NAObjectIdClassPrivate NAObjectIdClassPrivate;
+typedef struct _NAObjectIdClassPrivate NAObjectIdClassPrivate;
 
+/**
+ * NAObjectIdClass:
+ * @new_id: Allocate a new id to an existing NAObjectId.
+ *
+ * The #NAObjectIdClass defines some methods available to derived classes.
+ */
 typedef struct {
+	/*< private >*/
 	NAObjectClass           parent;
 	NAObjectIdClassPrivate *private;
 
+	/*< public >*/
 	/**
 	 * new_id:
-	 * @object: a #NAObjectId object.
-	 * @new_parent: possibly the new #NAObjectId parent, or NULL.
-	 * If not NULL, this should actually be a #NAObjectItem.
-	 *
-	 * Returns: a new id suitable for this @object.
+	 * @object: a NAObjectId object.
+	 * @new_parent: possibly the new NAObjectId parent, or NULL.
+	 * If not NULL, this should actually be a NAObjectItem.
 	 *
-	 * If @object is a #NAObjectProfile, then @new_parent must be a
-	 * not null #NAObjectAction. This function ensures that the new
+	 * If @object is a NAObjectProfile, then @new_parent must be a
+	 * not null NAObjectAction. This function ensures that the new
 	 * profile name does not already exist in the given @new_parent.
 	 *
 	 * This is a pure virtual function which should be implemented by
 	 * the actual class. Actually, we asks for the most-derived class
 	 * which implements this function.
+	 *
+	 * Returns: a new id suitable for this @object.
+	 *
+	 * Since: Nautilus-Actions v 2.30.
 	 */
 	gchar * ( *new_id )( const NAObjectId *object, const NAObjectId *new_parent );
 }
diff --git a/src/api/na-object.h b/src/api/na-object.h
index b5b5a56..8542ca5 100644
--- a/src/api/na-object.h
+++ b/src/api/na-object.h
@@ -34,7 +34,7 @@
 /**
  * SECTION: object
  * @title: NAObject
- * @short_description: The #NAObject Base Class Definition
+ * @short_description: The Deepest Base Class Definition
  * @include: nautilus-actions/na-object.h
  *
  * This is the base class of all our data object hierarchy. #NAObject is
diff --git a/src/core/na-object-id.c b/src/core/na-object-id.c
index b7b71e9..58a96e9 100644
--- a/src/core/na-object-id.c
+++ b/src/core/na-object-id.c
@@ -39,13 +39,13 @@
 
 /* private class data
  */
-struct NAObjectIdClassPrivate {
+struct _NAObjectIdClassPrivate {
 	void *empty;						/* so that gcc -pedantic is happy */
 };
 
 /* private instance data
  */
-struct NAObjectIdPrivate {
+struct _NAObjectIdPrivate {
 	gboolean   dispose_has_run;
 };
 
@@ -223,9 +223,20 @@ object_is_valid( const NAObject *object )
  * Sort the objects in alphabetical ascending order of their label.
  *
  * Returns:
- * -1 if @a must be sorted before @b,
- *  0 if @a and @b are equal from the local point of view,
- *  1 if @a must be sorted after @b.
+ *
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>-1 if @a must be sorted before @b,</para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>0 if @a and @b are equal from the local point of view,</para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>1 if @a must be sorted after @b.</para>
+ *   </listitem>
+ * </itemizedlist>
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gint
 na_object_id_sort_alpha_asc( const NAObjectId *a, const NAObjectId *b )
@@ -252,9 +263,20 @@ na_object_id_sort_alpha_asc( const NAObjectId *a, const NAObjectId *b )
  * Sort the objects in alphabetical descending order of their label.
  *
  * Returns:
- * -1 if @a must be sorted before @b,
- *  0 if @a and @b are equal from the local point of view,
- *  1 if @a must be sorted after @b.
+ *
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>-1 if @a must be sorted before @b,</para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>0 if @a and @b are equal from the local point of view,</para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>1 if @a must be sorted after @b.</para>
+ *   </listitem>
+ * </itemizedlist>
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gint
 na_object_id_sort_alpha_desc( const NAObjectId *a, const NAObjectId *b )
@@ -280,6 +302,8 @@ na_object_id_sort_alpha_desc( const NAObjectId *a, const NAObjectId *b )
  *
  * Actual relabeling takes place if @relabel is %TRUE, depending of the
  * user preferences.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_id_prepare_for_paste( NAObjectId *object, gboolean relabel, gboolean renumber, NAObjectId *parent )
@@ -326,6 +350,8 @@ na_object_id_prepare_for_paste( NAObjectId *object, gboolean relabel, gboolean r
  * @object: the #NAObjectId object whose label is to be changed.
  *
  * Sets the 'Copy of' label.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_id_set_copy_of_label( NAObjectId *object )
@@ -358,6 +384,8 @@ na_object_id_set_copy_of_label( NAObjectId *object )
  * existing ones.
  *
  * Request a new id to the derived class, and set it.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_id_set_new_id( NAObjectId *object, const NAObjectId *new_parent )
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]