Document new api

svn path=/trunk/; revision=6398

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

diff --git a/gio/gdrive.c b/gio/gdrive.c
index 2eb0237..18a7ecd 100644 (file)
--- a/gio/gdrive.c
+++ b/gio/gdrive.c
@@ -474,9 +474,20 @@ g_drive_poll_for_media_finish (GDrive        *drive,
   return (* iface->poll_for_media_finish) (drive, result, error);
 }
 
+/**
+ * g_drive_get_identifier:
+ * @drive: a #GDrive
+ * @kind: the kind of identifier to return
+ *
+ * Gets the identifier of the given kind for @drive.
+ *
+ * Returns: a newly allocated string containing the
+ *   requested identfier, or %NULL if the #GDrive
+ *   doesn't have this kind of identifier
+ */
 char *
-g_drive_get_identifier (GDrive              *drive,
-                       const char          *kind)
+g_drive_get_identifier (GDrive     *drive,
+                       const char *kind)
 {
   GDriveIface *iface;
 
@@ -491,6 +502,17 @@ g_drive_get_identifier (GDrive              *drive,
   return (* iface->get_identifier) (drive, kind);
 }
 
+/**
+ * g_drive_enumerate_identifiers:
+ * @drive: a #GDrive
+ *
+ * Gets the kinds of identifiers that @drive has. 
+ * Use g_drive_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_drive_enumerate_identifiers (GDrive *drive)
 {

diff --git a/gio/gdrive.h b/gio/gdrive.h
index e8afcb3..26671b9 100644 (file)
--- a/gio/gdrive.h
+++ b/gio/gdrive.h
@@ -59,6 +59,11 @@ G_BEGIN_DECLS
  * @eject_finish: Finishes an eject operation.
  * @poll_for_media: Poll for media insertion/removal on a #GDrive.
  * @poll_for_media_finish: Finishes a media poll operation.
+ * @get_identifier: Returns the identifier of the given kind, or %NULL if 
+ *    the #GDrive doesn't have one.
+ * @enumerate_identifiers: Returns an array strings listing the kinds
+ *    of identifiers which the #GDrive has.
+ *
  * 
  * Interface for creating #GDrive implementations.
  */