From: Sage Weil <sage@redhat.com>
Date: Thu, 26 Jan 2017 23:02:39 +0000 (-0500)
Subject: librados: document new object enumeration methods
X-Git-Tag: v12.0.1~413^2~1
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=fa90bfb247fa4819128083805974254b2988c0a9;p=ceph.git

librados: document new object enumeration methods

Signed-off-by: Sage Weil <sage@redhat.com>
---

diff --git a/src/include/rados/librados.h b/src/include/rados/librados.h
index 9d02093a2df..97765ac679b 100644
--- a/src/include/rados/librados.h
+++ b/src/include/rados/librados.h
@@ -1026,15 +1026,61 @@ CEPH_RADOS_API int rados_nobjects_list_next(rados_list_ctx_t ctx,
  */
 CEPH_RADOS_API void rados_nobjects_list_close(rados_list_ctx_t ctx);
 
-CEPH_RADOS_API rados_object_list_cursor rados_object_list_begin(rados_ioctx_t io);
+/**
+ * Get cursor handle pointing to the *beginning* of a pool.
+ *
+ * This is an opaque handle pointing to the start of a pool.  It must
+ * be released with rados_object_list_cursor_free().
+ *
+ * @param io ioctx for the pool
+ * @returns handle for the pool, NULL on error (pool does not exist)
+ */
+CEPH_RADOS_API rados_object_list_cursor rados_object_list_begin(
+  rados_ioctx_t io);
+
+/**
+ * Get cursor handle pointing to the *end* of a pool.
+ *
+ * This is an opaque handle pointing to the start of a pool.  It must
+ * be released with rados_object_list_cursor_free().
+ *
+ * @param io ioctx for the pool
+ * @returns handle for the pool, NULL on error (pool does not exist)
+ */
 CEPH_RADOS_API rados_object_list_cursor rados_object_list_end(rados_ioctx_t io);
 
+/**
+ * Check if a cursor has reached the end of a pool
+ *
+ * @param io ioctx
+ * @param cur cursor
+ * @returns 1 if the cursor has reached the end of the pool, 0 otherwise
+ */
 CEPH_RADOS_API int rados_object_list_is_end(rados_ioctx_t io,
     rados_object_list_cursor cur);
 
+/**
+ * Release a cursor
+ *
+ * Release a cursor.  The handle may not be used after this point.
+ *
+ * @param io ioctx
+ * @param cur cursor
+ */
 CEPH_RADOS_API void rados_object_list_cursor_free(rados_ioctx_t io,
     rados_object_list_cursor cur);
 
+/**
+ * Compare two cursor positions
+ *
+ * Compare two cursors, and indicate whether the first cursor precedes,
+ * matches, or follows the second.
+ *
+ * @param io ioctx
+ * @param lhs first cursor
+ * @param rhs second cursor
+ * @returns -1, 0, or 1 for lhs < rhs, lhs == rhs, or lhs > rhs
+ */
 CEPH_RADOS_API int rados_object_list_cursor_cmp(rados_ioctx_t io,
     rados_object_list_cursor lhs, rados_object_list_cursor rhs);
 
diff --git a/src/include/rados/librados.hpp b/src/include/rados/librados.hpp
index 6c7dcec10d7..6c9817e4aaa 100644
--- a/src/include/rados/librados.hpp
+++ b/src/include/rados/librados.hpp
@@ -865,14 +865,23 @@ namespace librados
     /// Iterator indicating the end of a pool
     const NObjectIterator& nobjects_end() const;
 
+    /// Get cursor for pool beginning
     ObjectCursor object_list_begin();
+
+    /// Get cursor for pool end
     ObjectCursor object_list_end();
+
+    /// Check whether a cursor is at the end of a pool
     bool object_list_is_end(const ObjectCursor &oc);
+
+    /// List some objects between two cursors
     int object_list(const ObjectCursor &start, const ObjectCursor &finish,
                     const size_t result_count,
                     const bufferlist &filter,
                     std::vector<ObjectItem> *result,
                     ObjectCursor *next);
+
+    /// Generate cursors that include the N out of Mth slice of the pool
     void object_list_slice(
         const ObjectCursor start,
         const ObjectCursor finish,