Document librbd::parent_spec and librbd::parent_info.

Add an explanatory comment to parent_types.h that explains what
the "overlap" member in parent_info means. This was not exactly easy
to figure out.

Signed-off-by: Krzysztof Kosiński <krzysztof.kosinski@intel.com>

diff --git a/src/librbd/parent_types.h b/src/librbd/parent_types.h
index 4dcc452962f951cd25a25a8d1c7aebf607952930..5c54953061ea651122a8aec63013f5c50cc75c7d 100644 (file)
--- a/src/librbd/parent_types.h
+++ b/src/librbd/parent_types.h
@@ -3,10 +3,10 @@
 #ifndef CEPH_LIBRBD_PARENT_TYPES_H
 #define CEPH_LIBRBD_PARENT_TYPES_H
 
-// parent_spec uniquely identifies a parent in the clone relationship
-// (clone(parent) creates child, then parent_spec <-> child_imageid)
-
 namespace librbd {
+  /** @brief Unique identification of a parent in clone relationship.
+   * Cloning an image creates a child image that keeps a reference
+   * to its parent. This allows copy-on-write images. */
   struct parent_spec {
     int64_t pool_id;
     string image_id;
@@ -24,9 +24,18 @@ namespace librbd {
     }
   };
 
+  /// Full information about an image's parent.
   struct parent_info {
+    /// Identification of the parent.
     parent_spec spec;
+
+    /** @brief Where the portion of data shared with the child image ends.
+     * Since images can be resized multiple times, the portion of data shared
+     * with the child image is not necessarily min(parent size, child size).
+     * If the child image is first shrunk and then enlarged, the common portion
+     * will be shorter. */
     uint64_t overlap;
+
     parent_info() : overlap(0) {}
   };
 }