From: Sage Weil <sage.weil@dreamhost.com>
Date: Thu, 2 Feb 2012 22:23:16 +0000 (-0800)
Subject: encoding: document ENCODE/DECODE macros
X-Git-Tag: v0.44~93^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=d597dc2d5bed09204cd1b521d8d576301cdce94e;p=ceph.git

encoding: document ENCODE/DECODE macros

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

diff --git a/src/include/encoding.h b/src/include/encoding.h
index f304502082ff..79a28c77a442 100644
--- a/src/include/encoding.h
+++ b/src/include/encoding.h
@@ -644,6 +644,13 @@ inline void decode(std::deque<T>& ls, bufferlist::iterator& p)
  * guards
  */
 
+/**
+ * start encoding block
+ *
+ * @param v current (code) version of the encoding
+ * @param compat oldest code version that can decode it
+ * @param bl bufferlist to encode to
+ */
 #define ENCODE_START(v, compat, bl)			     \
   __u8 struct_v = v, struct_compat = compat;		     \
   ::encode(struct_v, bl);				     \
@@ -653,6 +660,11 @@ inline void decode(std::deque<T>& ls, bufferlist::iterator& p)
   ::encode(struct_len, bl);				     \
   do {
 
+/**
+ * finish encoding block
+ *
+ * @param bl bufferlist we were encoding to
+ */
 #define ENCODE_FINISH(bl)						\
   } while (false);							\
   struct_len = bl.length() - struct_len_pos - sizeof(struct_len);	\
@@ -667,10 +679,23 @@ inline void decode(std::deque<T>& ls, bufferlist::iterator& p)
 #define DECODE_ERR_PAST(func) \
   "" #func " decode past end of struct encoding"
 
+/**
+ * check for very old encoding
+ *
+ * If the encoded data is older than oldestv, raise an exception.
+ *
+ * @param oldestv oldest version of the code we can successfully decode.
+ */
 #define DECODE_OLDEST(oldestv)						\
   if (struct_v < oldestv)						\
     throw buffer::malformed_input(DECODE_ERR_OLDVERSION(__PRETTY_FUNCTION__, v)); 
 
+/**
+ * start a decoding block
+ *
+ * @param v current version of the encoding that the code supports/encodes
+ * @param bl bufferlist::iterator for the encoded data
+ */
 #define DECODE_START(v, bl)						\
   __u8 struct_v, struct_compat;						\
   ::decode(struct_v, bl);						\
@@ -684,6 +709,20 @@ inline void decode(std::deque<T>& ls, bufferlist::iterator& p)
   unsigned struct_end = bl.get_off() + struct_len;			\
   do {
 
+/**
+ * start a decoding block with legacy support for older encoding schemes
+ *
+ * The old encoding schemes has a __u8 struct_v only, or lacked either
+ * the compat version or length.  Skip those fields conditionally.
+ *
+ * Most of the time, v, compatv, and lenv will all match the version
+ * where the structure was switched over to the new macros.
+ *
+ * @param v current version of the encoding that the code supports/encodes
+ * @param compatv oldest version that includes a __u8 compat version field
+ * @param lenv oldest version that includes a __u32 length wrapper
+ * @param bl bufferlist::iterator containing the encoded data
+ */
 #define DECODE_START_LEGACY_COMPAT_LEN(v, compatv, lenv, bl)		\
   __u8 struct_v;							\
   ::decode(struct_v, bl);						\
@@ -703,6 +742,11 @@ inline void decode(std::deque<T>& ls, bufferlist::iterator& p)
   }									\
   do {
 
+/**
+ * finish decode block
+ *
+ * @param bl bufferlist::iterator we were decoding from
+ */
 #define DECODE_FINISH(bl)						\
   } while (false);							\
   if (struct_end) {							\