Documentation additions

svn path=/trunk/; revision=6492

gio/ChangeLog

@@ -1,3 +1,12 @@
+2008-02-11  Matthias Clasen <mclasen@redhat.com>
+
+	* *.c: Documentation additions
+
+2008-02-10  Matthias Clasen <mclasen@redhat.com>
+
+	* gappinfo.h: Formatting cleanup
+	* gappinfo.c: Fix up docs.
+
 2008-02-09  Matthias Clasen <mclasen@redhat.com>
 
 	* gunixmounts.c: Consistently use getmntent_r() and fall

gio/gappinfo.c

@@ -532,7 +532,7 @@ g_app_info_should_show (GAppInfo *appinfo)
 /**
  * g_app_info_launch_default_for_uri:
  * @uri: the uri to show
- * @context: an optional #GAppLaunchContext.
+ * @launch_context: an optional #GAppLaunchContext.
  * @error: a #GError.
  *
  * Utility function that launches the default application 
@@ -543,9 +543,9 @@ g_app_info_should_show (GAppInfo *appinfo)
  * Returns: %TRUE on success, %FALSE on error.
  **/
 gboolean
-g_app_info_launch_default_for_uri (const char *uri,
+g_app_info_launch_default_for_uri (const char         *uri,
-				   GAppLaunchContext *launch_context,
+				   GAppLaunchContext  *launch_context,
-				   GError **error)
+				   GError            **error)
 {
   GAppInfo *app_info;
   GFile *file;

gio/gappinfo.h

@@ -186,9 +186,9 @@ GAppInfo *g_app_info_get_default_for_type        (const char  *content_type,
 						  gboolean     must_support_uris);
 GAppInfo *g_app_info_get_default_for_uri_scheme  (const char  *uri_scheme);
 
-gboolean g_app_info_launch_default_for_uri (const char *uri,
+gboolean  g_app_info_launch_default_for_uri      (const char              *uri,
-					    GAppLaunchContext *launch_context,
+					          GAppLaunchContext       *launch_context,
-					    GError **error);
+					          GError                 **error);
 
 /**
  * GAppLaunchContext:

gio/gdesktopappinfo.c

@@ -1662,7 +1662,9 @@ g_app_info_get_default_for_type (const char *content_type,
  * @uri_scheme: a string containing a URI scheme.
  *
  * Gets the default application for launching applications 
- * using this URI scheme.
+ * using this URI scheme. A URI scheme is the initial part 
+ * of the URI, up to but not including the ':', e.g. "http", 
+ * "ftp" or "sip".
  * 
  * Returns: #GAppInfo for given @uri_scheme or %NULL on error.
  **/
@@ -2520,9 +2522,22 @@ g_desktop_app_info_lookup_base_init (gpointer g_class)
 {
 }
 
+/**
+ * g_desktop_app_info_lookup_get_default_for_uri_scheme:
+ * @lookup: a #GDesktopAppInfoLookup
+ * @uri_scheme: a string containing a URI scheme.
+ *
+ * Gets the default application for launching applications 
+ * using this URI scheme.
+ *
+ * There should be little reason to use this function directly,
+ * it is preferred to use g_app_info_get_default_for_uri_scheme().
+ * 
+ * Returns: #GAppInfo for given @uri_scheme or %NULL on error.
+ */
 GAppInfo *
 g_desktop_app_info_lookup_get_default_for_uri_scheme (GDesktopAppInfoLookup *lookup,
-						      const char  *uri_scheme)
+						      const char            *uri_scheme)
 {
   GDesktopAppInfoLookupIface *iface;
   

gio/gdesktopappinfo.h

@@ -59,6 +59,12 @@ void             g_desktop_app_info_set_desktop_env   (const char *desktop_env);
 
 #define G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME "gio-desktop-app-info-lookup"
 
+/**
+ * GDesktopAppInfoLookup:
+ *
+ * Interface that is used by backends to associate default 
+ * handlers with URI schemes.
+ */
 typedef struct _GDesktopAppInfoLookup GDesktopAppInfoLookup;
 typedef struct _GDesktopAppInfoLookupIface GDesktopAppInfoLookupIface;
 
@@ -70,9 +76,9 @@ struct _GDesktopAppInfoLookupIface
 					    const char  *uri_scheme);
 };
 
-GType g_desktop_app_info_lookup_get_type (void) G_GNUC_CONST;
+GType     g_desktop_app_info_lookup_get_type (void) G_GNUC_CONST;
-GAppInfo * g_desktop_app_info_lookup_get_default_for_uri_scheme (GDesktopAppInfoLookup *lookup,
+GAppInfo *g_desktop_app_info_lookup_get_default_for_uri_scheme (GDesktopAppInfoLookup *lookup,
-								 const char  *uri_scheme);
+								const char  *uri_scheme);
 
 G_END_DECLS
 

gio/gdrive.c

@@ -216,6 +216,9 @@ g_drive_has_volumes (GDrive *drive)
  * 
  * Get a list of mountable volumes for @drive.
  *
+ * The returned list should be freed with g_list_free(), after
+ * its elements have been unreffed with g_object_unref().
+ * 
  * Returns: #GList containing any #GVolume<!---->s on the given @drive.
  **/
 GList *

gio/giomodule.c

@@ -41,11 +41,55 @@
  * @include: gio.h
  *
  * Provides an interface and default functions for loading and unloading 
- * modules. This is used internally to make gio extensible, but can also
+ * modules. This is used internally to make GIO extensible, but can also
- * be used by other to implement module loading.
+ * be used by others to implement module loading.
  * 
  **/
 
+/**
+ * SECTION:extensionpoints
+ * @short_description: Extension Points
+ * @include: gio.h
+ * @see_also: <link linkend="gio-extension-points">Extending GIO</link>
+ *
+ * #GIOExtensionPoint provides a mechanism for modules to extend the
+ * functionality of the library or application that loaded it in an 
+ * organized fashion.  
+ *
+ * An extension point is identified by a name, and it may optionally
+ * require that any implementation must by of a certain type (or derived
+ * thereof). Use g_io_extension_point_register() to register an
+ * extension point, and g_io_extension_point_set_required_type() to
+ * set a required type.
+ *
+ * A module can implement an extension point by specifying the #GType 
+ * that implements the functionality. Additionally, each implementation
+ * of an extension point has a name, and a priority. Use
+ * g_io_extension_point_implement() to implement an extension point.
+ * 
+ *  |[
+ *  GIOExtensionPoint *ep;
+ *
+ *  /&ast; Register an extension point &ast;/
+ *  ep = g_io_extension_point_register ("my-extension-point");
+ *  g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
+ *  ]|
+ *
+ *  |[
+ *  /&ast; Implement an extension point &ast;/
+ *  G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
+ *  g_io_extension_point_implement ("my-extension-point",
+ *                                  my_example_impl_get_type (),
+ *                                  "my-example",
+ *                                  10);
+ *  ]|
+ *
+ *  It is up to the code that registered the extension point how
+ *  it uses the implementations that have been associated with it.
+ *  Depending on the use case, it may use all implementations, or
+ *  only the one with the highest priority, or pick a specific
+ *  one by name. 
+ */
 struct _GIOModule {
   GTypeModule parent_instance;
   
@@ -323,6 +367,15 @@ g_io_extension_point_free (GIOExtensionPoint *ep)
   g_free (ep);
 }
 
+/**
+ * g_io_extension_point_register:
+ * @name: The name of the extension point
+ *
+ * Registers an extension point.
+ *
+ * Returns: the new #GIOExtensionPoint. This object is owned by GIO
+ *    and should not be freed
+ */
 GIOExtensionPoint *
 g_io_extension_point_register (const char *name)
 {
@@ -352,6 +405,15 @@ g_io_extension_point_register (const char *name)
   return ep;
 }
 
+/**
+ * g_io_extension_point_lookup:
+ * @name: the name of the extension point
+ *
+ * Looks up an existing extension point.
+ *
+ * Returns: the #GIOExtensionPoint, or %NULL if there is no
+ *    registered extension point with the given name
+ */
 GIOExtensionPoint *
 g_io_extension_point_lookup (const char *name)
 {
@@ -368,6 +430,14 @@ g_io_extension_point_lookup (const char *name)
   
 }
 
+/**
+ * g_io_extension_point_set_required_type:
+ * @extension_point: a #GIOExtensionPoint
+ * @type: the #GType to require
+ *
+ * Sets the required type for @extension_point to @type. 
+ * All implementations must henceforth have this type.
+ */
 void
 g_io_extension_point_set_required_type (GIOExtensionPoint *extension_point,
 					GType              type)
@@ -375,18 +445,47 @@ g_io_extension_point_set_required_type (GIOExtensionPoint *extension_point,
   extension_point->required_type = type;
 }
 
+/**
+ * g_io_extension_point_get_required_type:
+ * @extension_point: a #GIOExtensionPoint
+ *
+ * Gets the required type for @extension_point.
+ *
+ * Returns: the #GType that all implementations must have, 
+ *     or #G_TYPE_INVALID if the extension point has no required type
+ */
 GType
 g_io_extension_point_get_required_type (GIOExtensionPoint *extension_point)
 {
   return extension_point->required_type;
 }
 
+/**
+ * g_io_extension_point_get_extensions:
+ * @extension_point: a #GIOExtensionPoint
+ *
+ * Gets a list of all extensions that implement this extension point.
+ * The list is sorted by priority, beginning with the highest priority.
+ * 
+ * Returns: a #GList of #GIOExtension<!-- -->s. The list is owned by
+ *   GIO and should not be modified
+ */
 GList *
 g_io_extension_point_get_extensions (GIOExtensionPoint *extension_point)
 {
   return extension_point->extensions;
 }
 
+/**
+ * g_io_extension_point_get_extension_by_name:
+ * @extension_point: a #GIOExtensionPoint
+ * @name: the name of the extension to get
+ *
+ * Finds a #GIOExtension for an extension point by name.
+ *
+ * Returns: the #GIOExtension for @extension_point that has the
+ *    given name, or %NULL if there is no extension with that name
+ */
 GIOExtension *
 g_io_extension_point_get_extension_by_name (GIOExtensionPoint *extension_point,
 					    const char        *name)
@@ -414,11 +513,26 @@ extension_prio_compare (gconstpointer  a,
   return extension_b->priority - extension_a->priority;
 }
 
+/**
+ * g_io_extension_point_implement:
+ * @extension_point_name: the name of the extension point
+ * @type: the #GType to register as extension 
+ * @extension_name: the name for the extension
+ * @priority: the priority for the extension
+ *
+ * Registers @type as extension for the extension point with name
+ * @extension_point_name. 
+ *
+ * If @type has already been registered as an extension for this 
+ * extension point, the existing #GIOExtension object is returned.
+ *
+ * Returns: a #GIOExtension object for #GType
+ */
 GIOExtension *
 g_io_extension_point_implement (const char *extension_point_name,
-				GType type,
+				GType       type,
 				const char *extension_name,
-				gint priority)
+				gint        priority)
 {
   GIOExtensionPoint *extension_point;
   GIOExtension *extension;
@@ -463,25 +577,60 @@ g_io_extension_point_implement (const char *extension_point_name,
   return extension;
 }
 
+/**
+ * g_io_extension_ref_class:
+ * @extension: a #GIOExtension
+ *
+ * Gets a reference to the class for the type that is 
+ * associated with @extension.
+ *
+ * Returns: the #GTypeClass for the type of @extension
+ */
 GTypeClass *
 g_io_extension_ref_class (GIOExtension *extension)
 {
   return g_type_class_ref (extension->type);
 }
 
-
+/**
+ * g_io_extension_get_type:
+ * @extension: a #GIOExtension
+ *
+ * Gets the type associated with @extension.
+ *
+ * Returns: the type of @extension
+ */
 GType
 g_io_extension_get_type (GIOExtension *extension)
 {
   return extension->type;
 }
 
+/**
+ * g_io_extension_get_name:
+ * @extension: a #GIOExtension
+ *
+ * Gets the name under which @extension was registered.
+ *
+ * Note that the same type may be registered as extension
+ * for multiple extension points, under different names.
+ *
+ * Returns: the name of @extension.
+ */
 const char *
 g_io_extension_get_name (GIOExtension *extension)
 {
   return extension->name;
 }
 
+/**
+ * g_io_extension_get_priority:
+ * @extension: a #GIOExtension
+ *
+ * Gets the priority with which @extension was registered.
+ *
+ * Returns: the priority of @extension
+ */
 gint
 g_io_extension_get_priority (GIOExtension *extension)
 {

gio/giomodule.h

@@ -55,8 +55,8 @@ GIOModule *g_io_module_new      (const gchar *filename);
 
 GList *g_io_modules_load_all_in_directory            (const char *dirname);
 
-GIOExtensionPoint *g_io_extension_point_register              (const char        *extension_point);
+GIOExtensionPoint *g_io_extension_point_register              (const char        *name);
-GIOExtensionPoint *g_io_extension_point_lookup                (const char        *extension_point);
+GIOExtensionPoint *g_io_extension_point_lookup                (const char        *name);
 void               g_io_extension_point_set_required_type     (GIOExtensionPoint *extension_point,
 							       GType              type);
 GType              g_io_extension_point_get_required_type     (GIOExtensionPoint *extension_point);
@@ -78,8 +78,9 @@ GTypeClass*             g_io_extension_ref_class    (GIOExtension *extension);
  * g_io_module_load:
  * @module: a #GIOModule.
  * 
- * Required API for GIO modules to implement. This function is ran after the module
+ * Required API for GIO modules to implement. 
- * has been loaded into GIO, to initialize the module.
+ * This function is ran after the module has been loaded into GIO, 
+ * to initialize the module.
  **/
 void        g_io_module_load     (GIOModule   *module);
 
@@ -87,8 +88,9 @@ void        g_io_module_load     (GIOModule   *module);
  * g_io_module_unload:
  * @module: a #GIOModule.
  * 
- * Required API for GIO modules to implement. This function is ran when the module
+ * Required API for GIO modules to implement. 
- * is being unloaded from GIO, to finalize the module.
+ * This function is ran when the module is being unloaded from GIO, 
+ * to finalize the module.
  **/
 void        g_io_module_unload   (GIOModule   *module);
 

gio/glocaldirectorymonitor.h

@@ -58,9 +58,9 @@ struct _GLocalDirectoryMonitorClass {
 
 GType g_local_directory_monitor_get_type (void) G_GNUC_CONST;
 
-GFileMonitor* _g_local_directory_monitor_new (const char* dirname,
+GFileMonitor* _g_local_directory_monitor_new (const char         *dirname,
-					      GFileMonitorFlags flags,
+					      GFileMonitorFlags   flags,
-					      GError **error);
+					      GError            **error);
 
 G_END_DECLS
 

gio/glocalfilemonitor.h

@@ -52,9 +52,9 @@ struct _GLocalFileMonitorClass {
 
 GType g_local_file_monitor_get_type (void) G_GNUC_CONST;
 
-GFileMonitor* _g_local_file_monitor_new (const char* pathname,
+GFileMonitor* _g_local_file_monitor_new (const char         *pathname,
-					 GFileMonitorFlags flags,
+					 GFileMonitorFlags   flags,
-					 GError **error);
+					 GError            **error);
 
 G_END_DECLS
 

gio/gvolume.c

@@ -56,6 +56,19 @@
  * #GAsyncReady data to see if the operation was completed
  * successfully.  If an @error is present when g_volume_mount_finish()
  * is called, then it will be filled with any error information.
+ *
+ * <para id="volume-identifier">
+ * It is sometimes necessary to directly access the underlying 
+ * operating system object behind a volume (e.g. for passing a volume
+ * to an application via the commandline). For this purpose, GIO
+ * allows to obtain an 'identifier' for the volume. There can be
+ * different kinds of identifiers, such as Hal UDIs, filesystem labels,
+ * traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
+ * uuids. GIO uses predefind strings as names for the different kinds
+ * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, 
+ * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier() 
+ * to obtain an identifier for a volume.
+ * </para>
  **/
 
 static void g_volume_base_init (gpointer g_class);
@@ -288,6 +301,14 @@ g_volume_can_eject (GVolume *volume)
   return (* iface->can_eject) (volume);
 }
 
+/**
+ * g_volume_should_automount:
+ * @volume: a #GVolume
+ *
+ * Returns whether the volume should be automatically mounted.
+ * 
+ * Returns: %TRUE if the volume should be automatically mounted.
+ */
 gboolean
 g_volume_should_automount (GVolume *volume)
 {
@@ -442,6 +463,8 @@ g_volume_eject_finish (GVolume  *volume,
  * @kind: the kind of identifier to return
  *
  * Gets the identifier of the given kind for @volume. 
+ * See the <link linkend="volume-identifier">introduction</link>
+ * for more information about volume identifiers.
  *
  * Returns: a newly allocated string containing the
  *   requested identfier, or %NULL if the #GVolume
@@ -468,9 +491,9 @@ g_volume_get_identifier (GVolume    *volume,
  * g_volume_enumerate_identifiers:
  * @volume: a #GVolume
  * 
- * Gets the kinds of identifiers that @volume has. 
+ * Gets the kinds of <link linkend="volume-identifier">identifiers</link>
- * Use g_volume_get_identifer() to obtain the identifiers
+ * that @volume has. Use g_volume_get_identifer() to obtain 
- * themselves.
+ * the identifiers themselves.
  *
  * Returns: a %NULL-terminated array of strings containing
  *   kinds of identifiers. Use g_strfreev() to free.

gio/gvolume.h

@@ -34,10 +34,39 @@
 
 G_BEGIN_DECLS
 
+/**
+ * G_VOLUME_IDENTIFIER_KIND_HAL_UDI:
+ *
+ * The string used to obtain a Hal UDI with g_volume_get_identifier().
+ */
 #define G_VOLUME_IDENTIFIER_KIND_HAL_UDI "hal-udi"
+
+/**
+ * G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE:
+ *
+ * The string used to obtain a Unix device path with g_volume_get_identifier().
+ */
 #define G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE "unix-device"
+
+/**
+ * G_VOLUME_IDENTIFIER_KIND_LABEL:
+ *
+ * The string used to obtain a filesystem label with g_volume_get_identifier().
+ */
 #define G_VOLUME_IDENTIFIER_KIND_LABEL "label"
+
+/**
+ * G_VOLUME_IDENTIFIER_KIND_UUID:
+ *
+ * The string used to obtain a UUID with g_volume_get_identifier().
+ */
 #define G_VOLUME_IDENTIFIER_KIND_UUID "uuid"
+
+/**
+ * G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT:
+ *
+ * The string used to obtain a NFS mount with g_volume_get_identifier().
+ */
 #define G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT "nfs-mount"
 
 
@@ -62,10 +91,11 @@ G_BEGIN_DECLS
  * @mount_finish: Finishes a mount operation.
  * @eject: Ejects a given #GVolume.
  * @eject_finish: Finishes an eject operation.
- * @get_identifier: Returns the identifier of the given kind, or %NULL if 
+ * @get_identifier: Returns the <link linkend="volume-identifier">identifier</link> of the given kind, or %NULL if 
  *    the #GVolume doesn't have one.
  * @enumerate_identifiers: Returns an array strings listing the kinds
- *    of identifiers which the #GVolume has.
+ *    of <link linkend="volume-identifier">identifiers</link> which the #GVolume has.
+ * @should_automount: Returns %TRUE if the #GVolume should be automatically mounted.
  * 
  * Interface for implementing operations for mountable volumes.
  **/

gio/gvolumemonitor.c

@@ -239,10 +239,10 @@ g_volume_monitor_init (GVolumeMonitor *monitor)
  * 
  * Gets a list of drives connected to the system.
  * 
- * The returned list should be freed with g_list_free(), but
+ * The returned list should be freed with g_list_free(), after
- * its elements need not be freed.
+ * its elements have been unreffed with g_object_unref().
  *
- * Returns: a #GList of connected #GDrives - free with g_list_free(). 
+ * Returns: a #GList of connected #GDrive<!-- -->s
  **/
 GList *
 g_volume_monitor_get_connected_drives (GVolumeMonitor *volume_monitor)
@@ -262,10 +262,10 @@ g_volume_monitor_get_connected_drives (GVolumeMonitor *volume_monitor)
  * 
  * Gets a list of the volumes on the system.
  * 
- * The returned list should be freed with g_list_free(), but
+ * The returned list should be freed with g_list_free(), after
- * its elements need not be freed.
+ * its elements have been unreffed with g_object_unref().
  *
- * Returns: a #GList of #GVolume - free with g_list_free().
+ * Returns: a #GList of #GVolume<!-- -->s.
  **/
 GList *
 g_volume_monitor_get_volumes (GVolumeMonitor *volume_monitor)
@@ -285,10 +285,10 @@ g_volume_monitor_get_volumes (GVolumeMonitor *volume_monitor)
  * 
  * Gets a list of the mounts on the system.
  *
- * The returned list should be freed with g_list_free(), but
+ * The returned list should be freed with g_list_free(), after
- * its elements need not be freed.
+ * its elements have been unreffed with g_object_unref().
  * 
- * Returns: a #GList of #GMount - free with g_list_free().
+ * Returns: a #GList of #GMount<!-- -->s
  **/
 GList *
 g_volume_monitor_get_mounts (GVolumeMonitor *volume_monitor)