Document new api

svn path=/trunk/; revision=6397

diff --git a/gio/ChangeLog b/gio/ChangeLog
index 0a638fa0673521478b171ae24c0d650ec630b46a..58922baa8347704f73f854151b5c26a905617300 100644 (file)
--- a/gio/ChangeLog
+++ b/gio/ChangeLog
@@ -1,4 +1,6 @@
 2008-01-28  Matthias Clasen  <mclasen@redhat.com>
+       
+       * gvolume.[hc]: Document new API. 
 
        * gfile.c (g_file_copy_async): Fix docs
 

diff --git a/gio/gvolume.c b/gio/gvolume.c
index 8eebc9a6f40be603f524a64bc3de9096424113bb..9eb0703b6bbf9c19fc40fb1eccb7333f1c391eb0 100644 (file)
--- a/gio/gvolume.c
+++ b/gio/gvolume.c
@@ -420,9 +420,20 @@ g_volume_eject_finish (GVolume  *volume,
   return (* iface->eject_finish) (volume, result, error);
 }
 
+/**
+ * g_volume_get_identifier:
+ * @volume: a #GVolume
+ * @kind: the kind of identifier to return
+ *
+ * Gets the identifier of the given kind for @volume.
+ *
+ * Returns: a newly allocated string containing the
+ *   requested identfier, or %NULL if the #GVolume
+ *   doesn't have this kind of identifier
+ */
 char *
-g_volume_get_identifier (GVolume              *volume,
-                        const char          *kind)
+g_volume_get_identifier (GVolume    *volume,
+                        const char *kind)
 {
   GVolumeIface *iface;
 
@@ -437,6 +448,17 @@ g_volume_get_identifier (GVolume              *volume,
   return (* iface->get_identifier) (volume, kind);
 }
 
+/**
+ * g_volume_enumerate_identifiers:
+ * @volume: a #GVolume
+ *
+ * Gets the kinds of identifiers that @volume has. 
+ * Use g_volume_get_identifer() to obtain the identifiers
+ * themselves.
+ *
+ * Returns: a %NULL-terminated array of strings containing
+ *   kinds of identifiers. Use g_strfreev() to free.
+ */
 char **
 g_volume_enumerate_identifiers (GVolume *volume)
 {

diff --git a/gio/gvolume.h b/gio/gvolume.h
index 3a99c69ef083bad4c3c872c1325099782c4438c9..656a242559dd60da6da4c753f20f39305506a7b1 100644 (file)
--- a/gio/gvolume.h
+++ b/gio/gvolume.h
@@ -62,6 +62,10 @@ 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 
+ *    the #GVolume doesn't have one.
+ * @enumerate_identifiers: Returns an array strings listing the kinds
+ *    of identifiers which the #GVolume has.
  * 
  * Interface for implementing operations for mountable volumes.
  **/