From e2ba37ceb389a48eaa9912ca6cc241fcfa0c33ba Mon Sep 17 00:00:00 2001
From: Matthias Clasen <matthiasc@src.gnome.org>
Date: Mon, 28 Jan 2008 17:21:34 +0000
Subject: [PATCH] Document new api

svn path=/trunk/; revision=6397
---
 gio/ChangeLog |  2 ++
 gio/gvolume.c | 26 ++++++++++++++++++++++++--
 gio/gvolume.h |  4 ++++
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/gio/ChangeLog b/gio/ChangeLog
index 0a638fa06..58922baa8 100644
--- 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 8eebc9a6f..9eb0703b6 100644
--- 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 3a99c69ef..656a24255 100644
--- 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.
  **/