libnautilus-extension: add gtk-doc documentation coverage

A lot of the library was poorly documented. Make sure the output of the
documentation looks okay.

17 files changed, 231 insertions, 8 deletions

diff --git a/libnautilus-extension/nautilus-column-provider.c b/libnautilus-extension/nautilus-column-provider.c
index 230575b19..7732592da 100644
--- a/libnautilus-extension/nautilus-column-provider.c
+++ b/libnautilus-extension/nautilus-column-provider.c
@@ -26,6 +26,16 @@
 
 #include <glib-object.h>
 
+/**
+ * SECTION:nautilus-column-provider
+ * @title: NautilusColumnProvider
+ * @short_description: Interface to provide additional list view columns
+ * @include: libnautilus-extension/nautilus-column-provider.h
+ *
+ * #NautilusColumnProvider allows extension to provide additional columns
+ * in the file manager list view.
+ */
+
 static void
 nautilus_column_provider_base_init (gpointer g_class)
 {
diff --git a/libnautilus-extension/nautilus-column-provider.h b/libnautilus-extension/nautilus-column-provider.h
index 1ab6b7052..dd6c8e1f0 100644
--- a/libnautilus-extension/nautilus-column-provider.h
+++ b/libnautilus-extension/nautilus-column-provider.h
@@ -44,6 +44,14 @@ G_BEGIN_DECLS
 typedef struct _NautilusColumnProvider       NautilusColumnProvider;
 typedef struct _NautilusColumnProviderIface  NautilusColumnProviderIface;
 
+/**
+ * NautilusColumnProviderIface:
+ * @g_iface: The parent interface.
+ * @get_columns: Returns a #GList of #NautilusColumn.
+ *   See nautilus_column_provider_get_columns() for details.
+ *
+ * Interface for extensions to provide additional list view columns.
+ */
 struct _NautilusColumnProviderIface {
 	GTypeInterface g_iface;
 
diff --git a/libnautilus-extension/nautilus-column.c b/libnautilus-extension/nautilus-column.c
index 824792528..29e6149cd 100644
--- a/libnautilus-extension/nautilus-column.c
+++ b/libnautilus-extension/nautilus-column.c
@@ -50,6 +50,19 @@ struct _NautilusColumnDetails {
 G_DEFINE_TYPE (NautilusColumn, nautilus_column, G_TYPE_OBJECT);
 
 /**
+ * SECTION:nautilus-column
+ * @title: NautilusColumn
+ * @short_description: List view column descriptor object
+ * @include: libnautilus-extension/nautilus-column.h
+ *
+ * #NautilusColumn is an object that describes a column in the file manager
+ * list view. Extensions can provide #NautilusColumn by registering a
+ * #NautilusColumnProvider and returning them from
+ * nautilus_column_provider_get_columns(), which will be called by the main
+ * application when creating a view.
+ */
+
+/**
  * nautilus_column_new:
  * @name: identifier of the column
  * @attribute: the file attribute to be displayed in the column
diff --git a/libnautilus-extension/nautilus-extension-types.h b/libnautilus-extension/nautilus-extension-types.h
index 3e51c8291..ca7ec7fe5 100644
--- a/libnautilus-extension/nautilus-extension-types.h
+++ b/libnautilus-extension/nautilus-extension-types.h
@@ -34,11 +34,27 @@ G_BEGIN_DECLS
 
 #define NAUTILUS_TYPE_OPERATION_RESULT (nautilus_operation_result_get_type ())
 
-/* Handle for asynchronous interfaces.  These are opaque handles that must
- * be unique within an extension object.  These are returned by operations
- * that return NAUTILUS_OPERATION_IN_PROGRESS */
+/**
+ * NautilusOperationHandle:
+ *
+ * Handle for asynchronous interfaces. These are opaque handles that must
+ * be unique within an extension object. These are returned by operations
+ * that return #NAUTILUS_OPERATION_IN_PROGRESS.
+ */
 typedef struct _NautilusOperationHandle NautilusOperationHandle;
 
+/**
+ * NautilusOperationResult:
+ * @NAUTILUS_OPERATION_COMPLETE: the operation succeeded, and the extension
+ *  is done with the request.
+ * @NAUTILUS_OPERATION_FAILED: the operation failed.
+ * @NAUTILUS_OPERATION_IN_PROGRESS: the extension has begin an async operation.
+ *  When this value is returned, the extension must set the handle parameter
+ *  and call the callback closure when the operation is complete.
+ *
+ * Return values for asynchronous operations performed by the extension.
+ * See nautilus_info_provider_update_file_info().
+ */
 typedef enum {
 	/* Returned if the call succeeded, and the extension is done 
 	 * with the request */
@@ -56,6 +72,15 @@ typedef enum {
 
 GType nautilus_operation_result_get_type (void);
 
+/**
+ * SECTION:nautilus-extension-types
+ * @title: NautilusModule
+ * @short_description: Initialize an extension
+ * @include: libnautilus-extension/nautilus-extension-types.h
+ *
+ * Methods that each extension implements.
+ */
+
 void nautilus_module_initialize (GTypeModule  *module);
 void nautilus_module_shutdown   (void);
 void nautilus_module_list_types (const GType **types,
diff --git a/libnautilus-extension/nautilus-file-info.c b/libnautilus-extension/nautilus-file-info.c
index 3d2fb083e..329d5e5cb 100644
--- a/libnautilus-extension/nautilus-file-info.c
+++ b/libnautilus-extension/nautilus-file-info.c
@@ -25,6 +25,16 @@
 NautilusFileInfo *(*nautilus_file_info_getter) (GFile *location, gboolean create);
 
 /**
+ * SECTION:nautilus-file-info
+ * @title: NautilusFileInfo
+ * @short_description: File interface for nautilus extensions
+ * @include: libnautilus-extension/nautilus-file-info.h
+ *
+ * #NautilusFileInfo provides methods to get and modify information
+ * about file objects in the file manager.
+ */
+
+/**
  * nautilus_file_info_list_copy:
  * @files: (element-type NautilusFileInfo): the files to copy
  *
diff --git a/libnautilus-extension/nautilus-file-info.h b/libnautilus-extension/nautilus-file-info.h
index 32ae541ad..4660ad7c2 100644
--- a/libnautilus-extension/nautilus-file-info.h
+++ b/libnautilus-extension/nautilus-file-info.h
@@ -35,7 +35,6 @@ G_BEGIN_DECLS
 #define NAUTILUS_IS_FILE_INFO(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), NAUTILUS_TYPE_FILE_INFO))
 #define NAUTILUS_FILE_INFO_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), NAUTILUS_TYPE_FILE_INFO, NautilusFileInfoIface))
 
-
 #ifndef NAUTILUS_FILE_DEFINED
 #define NAUTILUS_FILE_DEFINED
 /* Using NautilusFile for the vtable to make implementing this in 
@@ -46,7 +45,50 @@ typedef struct NautilusFile          NautilusFile;
 typedef NautilusFile                  NautilusFileInfo;
 typedef struct _NautilusFileInfoIface NautilusFileInfoIface;
 
-
+/**
+ * NautilusFileInfoIface:
+ * @g_iface: The parent interface.
+ * @is_gone: Returns whether the file info is gone.
+ *   See nautilus_file_info_is_gone() for details.
+ * @get_name: Returns the file name as a string.
+ *   See nautilus_file_info_get_name() for details.
+ * @get_uri: Returns the file URI as a string.
+ *   See nautilus_file_info_get_uri() for details.
+ * @get_parent_uri: Returns the file parent URI as a string.
+ *   See nautilus_file_info_get_parent_uri() for details.
+ * @get_uri_scheme: Returns the file URI scheme as a string.
+ *   See nautilus_file_info_get_uri_scheme() for details.
+ * @get_mime_type: Returns the file mime type as a string.
+ *   See nautilus_file_info_get_mime_type() for details.
+ * @is_mime_type: Returns whether the file is the given mime type.
+ *   See nautilus_file_info_is_mime_type() for details.
+ * @is_directory: Returns whether the file is a directory.
+ *   See nautilus_file_info_is_directory() for details.
+ * @add_emblem: Adds an emblem to this file.
+ *   See nautilus_file_info_add_emblem() for details.
+ * @get_string_attribute: Returns the specified file attribute as a string.
+ *   See nautilus_file_info_get_string_attribute() for details.
+ * @add_string_attribute: Sets the specified string file attribute value.
+ *   See nautilus_file_info_add_string_attribute() for details.
+ * @invalidate_extension_info: Invalidates information of the file provided by extensions.
+ *   See nautilus_file_info_invalidate_extension_info() for details.
+ * @get_activation_uri: Returns the file activation URI as a string.
+ *   See nautilus_file_info_get_activation_uri() for details.
+ * @get_file_type: Returns the file type.
+ *   See nautilus_file_info_get_file_type() for details.
+ * @get_location: Returns the file location as a #GFile.
+ *   See nautilus_file_info_get_location() for details.
+ * @get_parent_location: Returns the file parent location as a #GFile.
+ *   See nautilus_file_info_get_parent_location() for details.
+ * @get_parent_info: Returns the file parent #NautilusFileInfo.
+ *   See nautilus_file_info_get_parent_info() for details.
+ * @get_mount: Returns the file mount as a #GMount.
+ *   See nautilus_file_info_get_mount() for details.
+ * @can_write: Returns whether the file is writable.
+ *   See nautilus_file_info_can_write() for details.
+ *
+ * Interface for extensions to provide additional menu items.
+ */
 struct _NautilusFileInfoIface 
 {
 	GTypeInterface g_iface;
diff --git a/libnautilus-extension/nautilus-info-provider.c b/libnautilus-extension/nautilus-info-provider.c
index 7adad2fea..b2cbbbac0 100644
--- a/libnautilus-extension/nautilus-info-provider.c
+++ b/libnautilus-extension/nautilus-info-provider.c
@@ -26,6 +26,18 @@
 
 #include <glib-object.h>
 
+/**
+ * SECTION:nautilus-info-provider
+ * @title: NautilusInfoProvider
+ * @short_description: Interface to provide additional information about files
+ * @include: libnautilus-extension/nautilus-column-provider.h
+ *
+ * #NautilusInfoProvider allows extension to provide additional information about
+ * files. When nautilus_info_provider_update_file_info() is called by the application,
+ * extensions will know that it's time to add extra information to the provided
+ * #NautilusFileInfo.
+ */
+
 static void
 nautilus_info_provider_base_init (gpointer g_class)
 {
diff --git a/libnautilus-extension/nautilus-info-provider.h b/libnautilus-extension/nautilus-info-provider.h
index 09cc19ec5..6d70887e9 100644
--- a/libnautilus-extension/nautilus-info-provider.h
+++ b/libnautilus-extension/nautilus-info-provider.h
@@ -47,7 +47,16 @@ typedef void (*NautilusInfoProviderUpdateComplete) (NautilusInfoProvider    *pro
 						    NautilusOperationHandle *handle,
 						    NautilusOperationResult  result,
 						    gpointer                 user_data);
-
+/**
+ * NautilusInfoProviderIface:
+ * @g_iface: The parent interface.
+ * @update_file_info: Returns a #NautilusOperationResult.
+ *   See nautilus_info_provider_update_file_info() for details.
+ * @cancel_update: Cancels a previous call to nautilus_info_provider_update_file_info().
+ *   See nautilus_info_provider_cancel_update() for details.
+ *
+ * Interface for extensions to provide additional information about files.
+ */
 struct _NautilusInfoProviderIface {
 	GTypeInterface g_iface;
 
diff --git a/libnautilus-extension/nautilus-location-widget-provider.c b/libnautilus-extension/nautilus-location-widget-provider.c
index 7865bf449..12d28ddeb 100644
--- a/libnautilus-extension/nautilus-location-widget-provider.c
+++ b/libnautilus-extension/nautilus-location-widget-provider.c
@@ -26,6 +26,16 @@
 
 #include <glib-object.h>
 
+/**
+ * SECTION:nautilus-location-widget-provider
+ * @title: NautilusLocationWidgetProvider
+ * @short_description: Interface to provide additional location widgets
+ * @include: libnautilus-extension/nautilus-location-widget-provider.h
+ *
+ * #NautilusLocationWidgetProvider allows extension to provide additional location
+ * widgets in the file manager views.
+ */
+
 static void
 nautilus_location_widget_provider_base_init (gpointer g_class)
 {
diff --git a/libnautilus-extension/nautilus-location-widget-provider.h b/libnautilus-extension/nautilus-location-widget-provider.h
index df874cfda..8000b2c19 100644
--- a/libnautilus-extension/nautilus-location-widget-provider.h
+++ b/libnautilus-extension/nautilus-location-widget-provider.h
@@ -45,6 +45,14 @@ G_BEGIN_DECLS
 typedef struct _NautilusLocationWidgetProvider       NautilusLocationWidgetProvider;
 typedef struct _NautilusLocationWidgetProviderIface  NautilusLocationWidgetProviderIface;
 
+/**
+ * NautilusLocationWidgetProviderIface:
+ * @g_iface: The parent interface.
+ * @get_widget: Returns a #GtkWidget.
+ *   See nautilus_location_widget_provider_get_widget() for details.
+ *
+ * Interface for extensions to provide additional location widgets.
+ */
 struct _NautilusLocationWidgetProviderIface {
 	GTypeInterface g_iface;
 
diff --git a/libnautilus-extension/nautilus-menu-item.c b/libnautilus-extension/nautilus-menu-item.c
index f0c5fed48..ee582dcde 100644
--- a/libnautilus-extension/nautilus-menu-item.c
+++ b/libnautilus-extension/nautilus-menu-item.c
@@ -57,6 +57,20 @@ static guint signals[LAST_SIGNAL];
 static GObjectClass *parent_class = NULL;
 
 /**
+ * SECTION:nautilus-menu-item
+ * @title: NautilusMenuItem
+ * @short_description: Menu item descriptor object
+ * @include: libnautilus-extension/nautilus-menu-item.h
+ *
+ * #NautilusMenuItem is an object that describes an item in a file manager
+ * menu. Extensions can provide #NautilusMenuItem objects by registering a
+ * #NautilusMenuProvider and returning them from
+ * nautilus_menu_provider_get_file_items(), or
+ * nautilus_menu_provider_get_background_items(), which will be called by the
+ * main application when creating menus.
+ */
+
+/**
  * nautilus_menu_item_new:
  * @name: the identifier for the menu item
  * @label: the user-visible label of the menu item
diff --git a/libnautilus-extension/nautilus-menu-provider.c b/libnautilus-extension/nautilus-menu-provider.c
index a81b721a3..0fb709469 100644
--- a/libnautilus-extension/nautilus-menu-provider.c
+++ b/libnautilus-extension/nautilus-menu-provider.c
@@ -27,6 +27,16 @@
 
 #include <glib-object.h>
 
+/**
+ * SECTION:nautilus-menu-provider
+ * @title: NautilusMenuProvider
+ * @short_description: Interface to provide additional menu items
+ * @include: libnautilus-extension/nautilus-menu-provider.h
+ *
+ * #NautilusMenuProvider allows extension to provide additional menu items
+ * in the file manager menus.
+ */
+
 static void
 nautilus_menu_provider_base_init (gpointer g_class)
 {
diff --git a/libnautilus-extension/nautilus-menu-provider.h b/libnautilus-extension/nautilus-menu-provider.h
index 297eaa263..23ff537be 100644
--- a/libnautilus-extension/nautilus-menu-provider.h
+++ b/libnautilus-extension/nautilus-menu-provider.h
@@ -45,6 +45,16 @@ G_BEGIN_DECLS
 typedef struct _NautilusMenuProvider       NautilusMenuProvider;
 typedef struct _NautilusMenuProviderIface  NautilusMenuProviderIface;
 
+/**
+ * NautilusMenuProviderIface:
+ * @g_iface: The parent interface.
+ * @get_file_items: Returns a #GList of #NautilusMenuItem.
+ *   See nautilus_menu_provider_get_file_items() for details.
+ * @get_background_items: Returns a #GList of #NautilusMenuItem.
+ *   See nautilus_menu_provider_get_background_items() for details.
+ *
+ * Interface for extensions to provide additional menu items.
+ */
 struct _NautilusMenuProviderIface {
 	GTypeInterface g_iface;
 
diff --git a/libnautilus-extension/nautilus-menu.c b/libnautilus-extension/nautilus-menu.c
index e274af853..ee7b2b2a8 100644
--- a/libnautilus-extension/nautilus-menu.c
+++ b/libnautilus-extension/nautilus-menu.c
@@ -26,6 +26,17 @@
 #include <glib.h>
 #include <glib/gi18n-lib.h>
 
+/**
+ * SECTION:nautilus-menu
+ * @title: NautilusMenu
+ * @short_description: Menu descriptor object
+ * @include: libnautilus-extension/nautilus-menu.h
+ *
+ * #NautilusMenu is an object that describes a submenu in a file manager
+ * menu. Extensions can provide #NautilusMenu objects by attaching them to
+ * #NautilusMenuItem objects, using nautilus_menu_item_set_submenu().
+ */
+
 #define NAUTILUS_MENU_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), NAUTILUS_TYPE_MENU, NautilusMenuPrivate))
 G_DEFINE_TYPE (NautilusMenu, nautilus_menu, G_TYPE_OBJECT);
 
diff --git a/libnautilus-extension/nautilus-property-page-provider.c b/libnautilus-extension/nautilus-property-page-provider.c
index 89211f34e..04a7f1f0f 100644
--- a/libnautilus-extension/nautilus-property-page-provider.c
+++ b/libnautilus-extension/nautilus-property-page-provider.c
@@ -27,6 +27,16 @@
 
 #include <glib-object.h>
 
+/**
+ * SECTION:nautilus-property-page-provider
+ * @title: NautilusPropertyPageProvider
+ * @short_description: Interface to provide additional property pages
+ * @include: libnautilus-extension/nautilus-property-page-provider.h
+ *
+ * #NautilusPropertyPageProvider allows extension to provide additional pages
+ * for the file properties dialog.
+ */
+
 static void
 nautilus_property_page_provider_base_init (gpointer g_class)
 {
diff --git a/libnautilus-extension/nautilus-property-page-provider.h b/libnautilus-extension/nautilus-property-page-provider.h
index 9bf932d10..1a3b36058 100644
--- a/libnautilus-extension/nautilus-property-page-provider.h
+++ b/libnautilus-extension/nautilus-property-page-provider.h
@@ -45,11 +45,19 @@ G_BEGIN_DECLS
 typedef struct _NautilusPropertyPageProvider       NautilusPropertyPageProvider;
 typedef struct _NautilusPropertyPageProviderIface  NautilusPropertyPageProviderIface;
 
+/**
+ * NautilusPropertyPageProviderIface:
+ * @g_iface: The parent interface.
+ * @get_pages: Returns a #GList of #NautilusPropertyPage.
+ *   See nautilus_property_page_provider_get_pages() for details.
+ *
+ * Interface for extensions to provide additional property pages.
+ */
 struct _NautilusPropertyPageProviderIface {
 	GTypeInterface g_iface;
 
-	GList *(*get_pages) (NautilusPropertyPageProvider     *provider,
-			     GList                    *files);
+	GList *(*get_pages) (NautilusPropertyPageProvider *provider,
+			     GList                        *files);
 };
 
 /* Interface Functions */
diff --git a/libnautilus-extension/nautilus-property-page.c b/libnautilus-extension/nautilus-property-page.c
index 115194cb1..545f2999f 100644
--- a/libnautilus-extension/nautilus-property-page.c
+++ b/libnautilus-extension/nautilus-property-page.c
@@ -43,6 +43,19 @@ struct _NautilusPropertyPageDetails {
 static GObjectClass *parent_class = NULL;
 
 /**
+ * SECTION:nautilus-property-page
+ * @title: NautilusPropertyPage
+ * @short_description: Property page descriptor object
+ * @include: libnautilus-extension/nautilus-property-page.h
+ *
+ * #NautilusPropertyPage is an object that describes a page in the file
+ * properties dialog. Extensions can provide #NautilusPropertyPage objects
+ * by registering a #NautilusPropertyPageProvider and returning them from
+ * nautilus_property_page_provider_get_pages(), which will be called by the
+ * main application when creating file properties dialogs.
+ */
+
+/**
  * nautilus_property_page_new:
  * @name: the identifier for the property page
  * @label: the user-visible label of the property page