GNOME.org
 

[nautilus-actions] Reference manual: Fix NAObjectItem documentation

commit 8838319b99760561b64ea2111e2fa00aef8c146d
Author: Pierre Wieser <pwieser trychlos org>
Date:   Sat Dec 11 16:46:45 2010 +0100

    Reference manual: Fix NAObjectItem documentation

 ChangeLog                                    |    8 +++
 docs/reference/nautilus-actions-docs.xml     |    2 +-
 docs/reference/nautilus-actions-sections.txt |   67 ++++++++++++++------------
 src/api/na-object-id.h                       |    2 +-
 src/api/na-object-item.h                     |   40 ++++++++++------
 src/core/na-object-item.c                    |   56 ++++++++++++++++------
 6 files changed, 112 insertions(+), 63 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 2c17587..9c56e2d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2010-12-11 Pierre Wieser <pwieser trychlos org>
 
+	Fix NAObjectItem documentation.
+
+	* docs/reference/nautilus-actions-docs.xml:
+	* docs/reference/nautilus-actions-sections.txt:
+	* src/api/na-object-id.h:
+	* src/api/na-object-item.h:
+	* src/core/na-object-item.c: Updated accordingly.
+
 	Fix NAObjectId documentation.
 
 	* docs/reference/nautilus-actions-docs.xml:
diff --git a/docs/reference/nautilus-actions-docs.xml b/docs/reference/nautilus-actions-docs.xml
index 46f96d5..8cc27d8 100644
--- a/docs/reference/nautilus-actions-docs.xml
+++ b/docs/reference/nautilus-actions-docs.xml
@@ -71,7 +71,7 @@
     <title>NAObject Hierarchy</title>
     <xi:include href="xml/object.xml"/>
     <xi:include href="xml/object-id.xml"/>
-    <xi:include href="xml/na-object-item.xml"/>
+    <xi:include href="xml/object-item.xml"/>
     <xi:include href="xml/na-object-action.xml"/>
     <xi:include href="xml/na-object-profile.xml"/>
     <xi:include href="xml/na-object-menu.xml"/>
diff --git a/docs/reference/nautilus-actions-sections.txt b/docs/reference/nautilus-actions-sections.txt
index 44b67c9..e5705bf 100644
--- a/docs/reference/nautilus-actions-sections.txt
+++ b/docs/reference/nautilus-actions-sections.txt
@@ -293,7 +293,7 @@ NAObjectClassPrivate
 </SECTION>
 
 # ---------------------------------------------------------------------
-# NAObjectId â?? The Identified Object Class Definition
+# NAObjectId â?? The Identified Object Base Class Definition
 
 <SECTION>
 <FILE>object-id</FILE>
@@ -321,40 +321,16 @@ NAObjectIdClassPrivate
 </SECTION>
 
 # ---------------------------------------------------------------------
-
-<SECTION>
-<FILE>iduplicable</FILE>
-NA_IDUPLICABLE_TYPE
-NA_IDUPLICABLE_GET_INTERFACE
-NAIDuplicable
-NAIDuplicableInterfacePrivate
-NAIDuplicableInterface
-NA_IDUPLICABLE_SIGNAL_STATUS_CHANGED
-na_iduplicable_dispose
-na_iduplicable_dump
-na_iduplicable_duplicate
-na_iduplicable_check_status
-na_iduplicable_get_origin
-na_iduplicable_is_valid
-na_iduplicable_is_modified
-na_iduplicable_set_origin
-na_iduplicable_set_modified
-na_iduplicable_register_consumer
-<SUBSECTION Standard>
-NA_IDUPLICABLE
-NA_IS_IDUPLICABLE
-na_iduplicable_get_type
-</SECTION>
-
-# ---------------------------------------------------------------------
+# NAObjectItem â?? The Object Item Base Class Definition 
 
 <SECTION>
 <FILE>object-item</FILE>
 <TITLE>NAObjectItem</TITLE>
 NA_OBJECT_ITEM_TYPE
-NAObjectItemPrivate
-NAObjectItemClassPrivate
+NA_OBJECT_ITEM
+NA_IS_OBJECT_ITEM
 NAObjectItem
+NAItemTarget
 na_object_item_are_equal
 na_object_item_get_item
 na_object_item_get_position
@@ -370,12 +346,41 @@ na_object_item_rebuild_children_slist
 na_object_item_deals_with_version
 
 <SUBSECTION Standard>
-NA_OBJECT_ITEM
-NA_IS_OBJECT_ITEM
 na_object_item_get_type
 NA_OBJECT_ITEM_CLASS
 NA_IS_OBJECT_ITEM_CLASS
 NA_OBJECT_ITEM_GET_CLASS
+NAObjectItemClass
+
+<SUBSECTION Private>
+NAObjectItemPrivate
+NAObjectItemClassPrivate
+</SECTION>
+
+# ---------------------------------------------------------------------
+
+<SECTION>
+<FILE>iduplicable</FILE>
+NA_IDUPLICABLE_TYPE
+NA_IDUPLICABLE_GET_INTERFACE
+NAIDuplicable
+NAIDuplicableInterfacePrivate
+NAIDuplicableInterface
+NA_IDUPLICABLE_SIGNAL_STATUS_CHANGED
+na_iduplicable_dispose
+na_iduplicable_dump
+na_iduplicable_duplicate
+na_iduplicable_check_status
+na_iduplicable_get_origin
+na_iduplicable_is_valid
+na_iduplicable_is_modified
+na_iduplicable_set_origin
+na_iduplicable_set_modified
+na_iduplicable_register_consumer
+<SUBSECTION Standard>
+NA_IDUPLICABLE
+NA_IS_IDUPLICABLE
+na_iduplicable_get_type
 </SECTION>
 
 # ---------------------------------------------------------------------
diff --git a/src/api/na-object-id.h b/src/api/na-object-id.h
index 0fb2ae7..08e05ed 100644
--- a/src/api/na-object-id.h
+++ b/src/api/na-object-id.h
@@ -34,7 +34,7 @@
 /**
  * SECTION: object-id
  * @title: NAObjectId
- * @short_description: The Identified Object Class Definition
+ * @short_description: The Identified Object Base Class Definition
  * @include: nautilus-actions/na-object-id.h
  *
  * This is a pure virtual class, i.e. not an instantiatable one.
diff --git a/src/api/na-object-item.h b/src/api/na-object-item.h
index 4ffa72c..86cfb5a 100644
--- a/src/api/na-object-item.h
+++ b/src/api/na-object-item.h
@@ -33,7 +33,8 @@
 
 /**
  * SECTION: object-item
- * @short_description: #NAObjectItem class definition.
+ * @title: NAObjectItem
+ * @short_description: The Object Item Base Class Definition
  * @include: nautilus-actions/na-object-item.h
  *
  * This is a pure virtual class, i.e. not an instantiatable one, but
@@ -44,41 +45,50 @@
 
 G_BEGIN_DECLS
 
-#define NA_OBJECT_ITEM_TYPE					( na_object_item_get_type())
-#define NA_OBJECT_ITEM( object )			( G_TYPE_CHECK_INSTANCE_CAST( object, NA_OBJECT_ITEM_TYPE, NAObjectItem ))
-#define NA_OBJECT_ITEM_CLASS( klass )		( G_TYPE_CHECK_CLASS_CAST( klass, NA_OBJECT_ITEM_TYPE, NAObjectItemClass ))
-#define NA_IS_OBJECT_ITEM( object )			( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_OBJECT_ITEM_TYPE ))
-#define NA_IS_OBJECT_ITEM_CLASS( klass )	( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_OBJECT_ITEM_TYPE ))
-#define NA_OBJECT_ITEM_GET_CLASS( object )	( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_OBJECT_ITEM_TYPE, NAObjectItemClass ))
+#define NA_OBJECT_ITEM_TYPE                  ( na_object_item_get_type())
+#define NA_OBJECT_ITEM( object )             ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_OBJECT_ITEM_TYPE, NAObjectItem ))
+#define NA_OBJECT_ITEM_CLASS( klass )        ( G_TYPE_CHECK_CLASS_CAST( klass, NA_OBJECT_ITEM_TYPE, NAObjectItemClass ))
+#define NA_IS_OBJECT_ITEM( object )          ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_OBJECT_ITEM_TYPE ))
+#define NA_IS_OBJECT_ITEM_CLASS( klass )     ( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_OBJECT_ITEM_TYPE ))
+#define NA_OBJECT_ITEM_GET_CLASS( object )   ( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_OBJECT_ITEM_TYPE, NAObjectItemClass ))
 
-typedef struct NAObjectItemPrivate      NAObjectItemPrivate;
+typedef struct _NAObjectItemPrivate      NAObjectItemPrivate;
 
 typedef struct {
+	/*< private >*/
 	NAObjectId           parent;
 	NAObjectItemPrivate *private;
 }
 	NAObjectItem;
 
-typedef struct NAObjectItemClassPrivate NAObjectItemClassPrivate;
+typedef struct _NAObjectItemClassPrivate NAObjectItemClassPrivate;
 
 typedef struct {
+	/*< private >*/
 	NAObjectIdClass           parent;
 	NAObjectItemClassPrivate *private;
 }
 	NAObjectItemClass;
 
-/* targets
+/**
+ * NAItemTarget:
+ * @ITEM_TARGET_SELECTION: when targeting the selection context menu.
+ * @ITEM_TARGET_LOCATION:  when targeting the background context menu.
+ * @ITEM_TARGET_TOOLBAR:   when targeting the toolbar.
+ * @ITEM_TARGET_ANY:       a wilcard target defined in order to be able
+ *                         to activate an action from a keyboard shortcut,
+ *                         while keeping this same action hidden from the UI.
  *
- * ITEM_TARGET_ANY is just a wilcard target defined in order to be able
- * to activate an action from a keyboard shortcut, while keeping this
- * same action hidden from the UI.
+ * The #NAItemTarget mode is Nautilus-driven. It determines in which part
+ * of the Nautilus UI our actions will be displayed.
  */
-enum {
+typedef enum {
 	ITEM_TARGET_SELECTION = 1,
 	ITEM_TARGET_LOCATION,
 	ITEM_TARGET_TOOLBAR,
 	ITEM_TARGET_ANY
-};
+}
+	NAItemTarget;
 
 GType       na_object_item_get_type( void );
 
diff --git a/src/core/na-object-item.c b/src/core/na-object-item.c
index 98343cc..f9562b0 100644
--- a/src/core/na-object-item.c
+++ b/src/core/na-object-item.c
@@ -43,13 +43,13 @@
 
 /* private class data
  */
-struct NAObjectItemClassPrivate {
+struct _NAObjectItemClassPrivate {
 	void *empty;						/* so that gcc -pedantic is happy */
 };
 
 /* private instance data
  */
-struct NAObjectItemPrivate {
+struct _NAObjectItemPrivate {
 	gboolean   dispose_has_run;
 
 	void      *provider_data;
@@ -273,8 +273,6 @@ object_id_new_id( const NAObjectId *item, const NAObjectId *new_parent )
  * @a: the first (original) #NAObjectItem instance.
  * @b: the second #NAObjectItem instance.
  *
- * Returns: %TRUE if @a is equal to @b.
- *
  * This function participates to the #na_iduplicable_check_status() stack,
  * and is triggered after all comparable elementary data (in #NAIFactoryObject
  * sense) have already been successfully compared.
@@ -284,6 +282,10 @@ object_id_new_id( const NAObjectId *item, const NAObjectId *new_parent )
  *
  * Note that, when called from na_object_check_status, the status of children
  * have already been checked, and so we should be able to rely on them.
+ *
+ * Returns: %TRUE if @a is equal to @b.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_object_item_are_equal( const NAObjectItem *a, const NAObjectItem *b )
@@ -389,10 +391,12 @@ na_object_item_are_equal( const NAObjectItem *a, const NAObjectItem *b )
  * @item: the #NAObjectItem from which we want retrieve a subitem.
  * @id: the id of the searched subitem.
  *
- * Returns: a pointer to the #NAObjectId-derived child with the required id.
+ * Returns: a pointer to the #NAObjectId -derived child with the required id.
  *
  * The returned #NAObjectId is owned by the @item object ; the
  * caller should not try to g_free() nor g_object_unref() it.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 NAObjectId *
 na_object_item_get_item( const NAObjectItem *item, const gchar *id )
@@ -423,10 +427,12 @@ na_object_item_get_item( const NAObjectItem *item, const gchar *id )
 /**
  * na_object_item_get_position:
  * @item: this #NAObjectItem object.
- * @child: a #NAObjectId-derived child.
+ * @child: a #NAObjectId -derived child.
  *
  * Returns: the position of @child in the subitems list of @item,
  * starting from zero, or -1 if not found.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gint
 na_object_item_get_position( const NAObjectItem *item, const NAObjectId *child )
@@ -459,6 +465,8 @@ na_object_item_get_position( const NAObjectItem *item, const NAObjectId *child )
  * and setup the parent pointer of the child to its new parent.
  *
  * Doesn't modify the reference count on @object.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_item_append_item( NAObjectItem *item, const NAObjectId *child )
@@ -484,12 +492,14 @@ na_object_item_append_item( NAObjectItem *item, const NAObjectId *child )
 /**
  * na_object_item_insert_at:
  * @item: the #NAObjectItem in which add the subitem.
- * @child: a #NAObjectId-derived to be inserted in the list of subitems.
+ * @child: a #NAObjectId -derived to be inserted in the list of subitems.
  * @pos: the position at which the @child should be inserted.
  *
  * Inserts a new @child in the list of subitems of @item.
  *
  * Doesn't modify the reference count on @child.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_item_insert_at( NAObjectItem *item, const NAObjectId *child, gint pos )
@@ -528,6 +538,8 @@ na_object_item_insert_at( NAObjectItem *item, const NAObjectId *child, gint pos
  * Inserts a new @child in the list of subitems of @item.
  *
  * Doesn't modify the reference count on @child.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_item_insert_item( NAObjectItem *item, const NAObjectId *child, const NAObjectId *before )
@@ -564,11 +576,13 @@ na_object_item_insert_item( NAObjectItem *item, const NAObjectId *child, const N
 /**
  * na_object_item_remove_item:
  * @item: the #NAObjectItem from which the subitem must be removed.
- * @child: a #NAObjectId-derived to be removed from the list of subitems.
+ * @child: a #NAObjectId -derived to be removed from the list of subitems.
  *
  * Removes a @child from the list of subitems of @item.
  *
  * Doesn't modify the reference count on @child.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_item_remove_item( NAObjectItem *item, const NAObjectId *child )
@@ -599,6 +613,8 @@ na_object_item_remove_item( NAObjectItem *item, const NAObjectId *child )
  * @item: the #NAObjectItem from which we want a count of subitems.
  *
  * Returns: the count of subitems of @item.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 guint
 na_object_item_get_items_count( const NAObjectItem *item )
@@ -620,17 +636,19 @@ na_object_item_get_items_count( const NAObjectItem *item )
 
 /**
  * na_object_item_count_items:
- * @items: a list if #NAObject-derived to be counted.
+ * @items: a list if #NAObject -derived to be counted.
  * @menus: will be set to the count of menus.
  * @actions: will be set to the count of actions.
  * @profiles: will be set to the count of profiles.
  * @recurse: whether to recursively count all items, or only those in
  *  level zero of the list.
  *
- * Count the numbers of items if the provided list.
+ * Returns: the count the numbers of items if the provided list.
  *
  * As this function is recursive, the counters should be initialized by
  * the caller before calling it.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_item_count_items( GList *items, gint *menus, gint *actions, gint *profiles, gboolean recurse )
@@ -663,11 +681,13 @@ na_object_item_count_items( GList *items, gint *menus, gint *actions, gint *prof
 
 /**
  * na_object_item_unref_items:
- * @items: a list of #NAObject-derived items.
+ * @items: a list of #NAObject -derived items.
  *
  * Unref only the first level the #NAObject of the list, freeing the list at last.
  *
- * This is rather only used by #NAPivot.
+ * This is rather only used by NAPivot.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_item_unref_items( GList *items )
@@ -678,11 +698,13 @@ na_object_item_unref_items( GList *items )
 
 /**
  * na_object_item_unref_items_rec:
- * @items: a list of #NAObject-derived items.
+ * @items: a list of #NAObject -derived items.
  *
  * Recursively unref the #NAObject's of the list, freeing the list at last.
  *
  * This is heavily used by NACT.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_item_unref_items_rec( GList *items )
@@ -698,7 +720,7 @@ na_object_item_unref_items_rec( GList *items )
 
 /**
  * na_object_item_deals_with_version:
- * @item: this #NAObjectItem-derived object.
+ * @item: this #NAObjectItem -derived object.
  *
  * Just after the @item has been readen from NAIFactoryProvider, setup
  * the version. This is needed because some conversions may occur in
@@ -707,6 +729,8 @@ na_object_item_unref_items_rec( GList *items )
  * Note that there is only some 2.x versions where the version string
  * was not systematically written. If @item has been readen from a
  * .desktop file, then iversion is already set to (at least) 3.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_item_deals_with_version( NAObjectItem *item )
@@ -738,9 +762,11 @@ na_object_item_deals_with_version( NAObjectItem *item )
 
 /**
  * na_object_item_rebuild_children_slist:
- * @item: this #NAObjectItem-derived object.
+ * @item: this #NAObjectItem -derived object.
  *
  * Rebuild the string list of children.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_object_item_rebuild_children_slist( NAObjectItem *item )
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]