gnome/nautilus
gnome/nautilus
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/nautilus synced 2024-07-05 01:41:28 +00:00
Code Issues Projects Releases Wiki Activity

libnautilus-extension: add gtk-doc documentation coverage

Browse Source 
A lot of the library was poorly documented. Make sure the output of the
documentation looks okay.
This commit is contained in:
Cosimo Cecchi 2015-05-25 20:33:13 -07:00
parent 545a7660fa
commit ff5a48d133
20 changed files with 257 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/libnautilus-extension/Makefile.am
View File

@ -34,7 +34,7 @@ CFILE_GLOB=$(top_srcdir)/libnautilus-extension/*.c
# Header files to ignore when scanning.
IGNORE_HFILES = \
config.h \
nautilus-extension-private.h \
$(NULL)
# Images to copy into HTML directory

1
docs/reference/libnautilus-extension/libnautilus-extension-docs.xml
View File

@ -24,6 +24,7 @@
<xi:include href="xml/nautilus-location-widget-provider.xml" />
<xi:include href="xml/nautilus-menu-provider.xml" />
<xi:include href="xml/nautilus-menu.xml" />
<xi:include href="xml/nautilus-menu-item.xml" />
<xi:include href="xml/nautilus-property-page-provider.xml" />
<xi:include href="xml/nautilus-property-page.xml" />
</chapter>

52
docs/reference/libnautilus-extension/libnautilus-extension-sections.txt
View File

@ -28,26 +28,11 @@ NAUTILUS_MENU_PROVIDER_GET_IFACE
<SECTION>
<FILE>nautilus-menu</FILE>
NAUTILUS_TYPE_MENU_ITEM
NAUTILUS_MENU_ITEM
NAUTILUS_MENU_ITEM_CLASS
NAUTILUS_MENU_IS_ITEM
NAUTILUS_MENU_IS_ITEM_CLASS
NAUTILUS_MENU_ITEM_GET_CLASS
NautilusMenuPrivate
NautilusMenuItemDetails
<TITLE>NautilusMenu</TITLE>
NautilusMenu
<TITLE>NautilusMenuItem</TITLE>
NautilusMenuItem
nautilus_menu_new
nautilus_menu_append_item
nautilus_menu_get_items
nautilus_menu_item_list_free
nautilus_menu_item_get_type
nautilus_menu_item_new
nautilus_menu_item_activate
nautilus_menu_item_set_submenu
<SUBSECTION Standard>
NAUTILUS_MENU
NAUTILUS_IS_MENU
@ -58,6 +43,24 @@ NAUTILUS_IS_MENU_CLASS
NAUTILUS_MENU_GET_CLASS
</SECTION>
<SECTION>
<FILE>nautilus-menu-item</FILE>
NautilusMenuItem
nautilus_menu_item_list_free
nautilus_menu_item_get_type
nautilus_menu_item_new
nautilus_menu_item_activate
nautilus_menu_item_set_submenu
<SUBSECTION Standard>
NAUTILUS_TYPE_MENU_ITEM
NAUTILUS_MENU_ITEM
NAUTILUS_MENU_ITEM_CLASS
NAUTILUS_MENU_IS_ITEM
NAUTILUS_MENU_IS_ITEM_CLASS
NAUTILUS_MENU_ITEM_GET_CLASS
NautilusMenuItemDetails
</SECTION>
<SECTION>
<FILE>nautilus-column-provider</FILE>
NautilusColumnProvider
@ -92,7 +95,6 @@ NautilusFileInfo
NautilusFileInfoIface
nautilus_file_info_create
nautilus_file_info_create_for_uri
nautilus_file_info_getter
nautilus_file_info_lookup
nautilus_file_info_lookup_for_uri
nautilus_file_info_list_copy
@ -126,8 +128,6 @@ NAUTILUS_FILE_INFO_GET_IFACE
<SECTION>
<FILE>nautilus-column</FILE>
NautilusColumnDetails
<TITLE>NautilusColumn</TITLE>
NautilusColumn
nautilus_column_new
<SUBSECTION Standard>
@ -138,6 +138,7 @@ nautilus_column_get_type
NAUTILUS_COLUMN_CLASS
NAUTILUS_INFO_IS_COLUMN_CLASS
NAUTILUS_COLUMN_GET_CLASS
NautilusColumnDetails
</SECTION>
<SECTION>
@ -145,10 +146,14 @@ NAUTILUS_COLUMN_GET_CLASS
NautilusInfoProvider
NautilusInfoProviderIface
NautilusInfoProviderUpdateComplete
NautilusOperationHandle
NautilusOperationResult
nautilus_info_provider_update_file_info
nautilus_info_provider_cancel_update
nautilus_info_provider_update_complete_invoke
<SUBSECTION Standard>
NAUTILUS_TYPE_OPERATION_RESULT
nautilus_operation_result_get_type
NAUTILUS_INFO_PROVIDER
NAUTILUS_IS_INFO_PROVIDER
NAUTILUS_TYPE_INFO_PROVIDER
@ -158,8 +163,6 @@ NAUTILUS_INFO_PROVIDER_GET_IFACE
<SECTION>
<FILE>nautilus-property-page</FILE>
NautilusPropertyPageDetails
<TITLE>NautilusPropertyPage</TITLE>
NautilusPropertyPage
nautilus_property_page_new
<SUBSECTION Standard>
@ -170,20 +173,13 @@ nautilus_property_page_get_type
NAUTILUS_PROPERTY_PAGE_CLASS
NAUTILUS_IS_PROPERTY_PAGE_CLASS
NAUTILUS_PROPERTY_PAGE_GET_CLASS
NautilusPropertyPageDetails
</SECTION>
<SECTION>
<FILE>nautilus-extension-types</FILE>
NAUTILUS_TYPE_OPERATION_RESULT
NautilusOperationHandle
NautilusOperationResult
nautilus_operation_result_get_type
nautilus_module_initialize
nautilus_module_shutdown
nautilus_module_list_types
</SECTION>
<SECTION>
<FILE>nautilus-menu-item</FILE>
</SECTION>

10
libnautilus-extension/nautilus-column-provider.c
View File

@ -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)
{

8
libnautilus-extension/nautilus-column-provider.h
View File

@ -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;

13
libnautilus-extension/nautilus-column.c
View File

@ -49,6 +49,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

31
libnautilus-extension/nautilus-extension-types.h
View File

@ -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,

10
libnautilus-extension/nautilus-file-info.c
View File

@ -24,6 +24,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

46
libnautilus-extension/nautilus-file-info.h
View File

@ -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;

12
libnautilus-extension/nautilus-info-provider.c
View File

@ -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)
{

11
libnautilus-extension/nautilus-info-provider.h
View File

@ -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;

10
libnautilus-extension/nautilus-location-widget-provider.c
View File

@ -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)
{

8
libnautilus-extension/nautilus-location-widget-provider.h
View File

@ -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;

14
libnautilus-extension/nautilus-menu-item.c
View File

@ -56,6 +56,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

10
libnautilus-extension/nautilus-menu-provider.c
View File

@ -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)
{

10
libnautilus-extension/nautilus-menu-provider.h
View File

@ -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;

11
libnautilus-extension/nautilus-menu.c
View File

@ -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);

10
libnautilus-extension/nautilus-property-page-provider.c
View File

@ -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)
{

12
libnautilus-extension/nautilus-property-page-provider.h
View File

@ -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 */

13
libnautilus-extension/nautilus-property-page.c
View File

@ -42,6 +42,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