Merge pull request #407 from redboltz/add_doc

Added unpack, pack, object, and object_handle documentation.

Author: redboltz

include/msgpack/object.hpp

@@ -29,23 +29,42 @@ namespace msgpack {
 MSGPACK_API_VERSION_NAMESPACE(v1) {
 /// @endcond
 
+/// The class holds object and zone
 class object_handle {
 public:
+    /// Constructor that creates nil object and null zone.
     object_handle() {}
 
+    /// Constructor that creates an object_handle holding object `obj` and zone `z`.
+    /**
+     * @param obj object
+     * @param z zone
+     */
     object_handle(msgpack::object const& obj, msgpack::unique_ptr<msgpack::zone> z) :
         m_obj(obj), m_zone(msgpack::move(z)) { }
 
     // obsolete
     void set(msgpack::object const& obj)
         { m_obj = obj; }
 
+    /// Get object reference
+    /**
+     * @return object
+     */
     const msgpack::object& get() const
         { return m_obj; }
 
+    /// Get unique_ptr reference of zone.
+    /**
+     * @return unique_ptr reference of zone
+     */
     msgpack::unique_ptr<msgpack::zone>& zone()
         { return m_zone; }
 
+    /// Get unique_ptr const reference of zone.
+    /**
+     * @return unique_ptr const reference of zone
+     */
     const msgpack::unique_ptr<msgpack::zone>& zone() const
         { return m_zone; }
 
@@ -133,6 +152,14 @@ inline std::size_t aligned_zone_size(msgpack::object const& obj) {
     return s;
 }
 
+/// clone object
+/**
+ * Clone (deep copy) object.
+ * The copied object is located on newly allocated zone.
+ * @param obj copy source object
+ *
+ * @return object_handle that holds deep copied object and zone.
+ */
 inline object_handle clone(msgpack::object const& obj) {
     std::size_t size = msgpack::aligned_zone_size(obj);
     msgpack::unique_ptr<msgpack::zone> z(size == 0 ? nullptr : new msgpack::zone(size));

include/msgpack/object_fwd.hpp

@@ -99,7 +99,10 @@ struct has_as {
 
 #endif // !defined(MSGPACK_USE_CPP03)
 
-
+/// Object class that corresponding to MessagePack format object
+/**
+ * See https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_object
+ */
 struct object {
     union union_type {
         bool boolean;
@@ -119,42 +122,114 @@ struct object {
     msgpack::type::object_type type;
     union_type via;
 
+    /// Cheking nil
+    /**
+     * @return If the object is nil, then return true, else return false.
+     */
     bool is_nil() const { return type == msgpack::type::NIL; }
 
 #if defined(MSGPACK_USE_CPP03)
 
+    /// Get value as T
+    /**
+     * If the object can't be converted to T, msgpack::type_error would be thrown.
+     * @tparam T The type you want to get.
+     * @return The converted object.
+     */
     template <typename T>
     T as() const;
 
 #else  // defined(MSGPACK_USE_CPP03)
 
+    /// Get value as T
+    /**
+     * If the object can't be converted to T, msgpack::type_error would be thrown.
+     * @tparam T The type you want to get.
+     * @return The converted object.
+     */
     template <typename T>
     typename std::enable_if<msgpack::has_as<T>::value, T>::type as() const;
 
+    /// Get value as T
+    /**
+     * If the object can't be converted to T, msgpack::type_error would be thrown.
+     * @tparam T The type you want to get.
+     * @return The converted object.
+     */
     template <typename T>
     typename std::enable_if<!msgpack::has_as<T>::value, T>::type as() const;
 
 #endif // defined(MSGPACK_USE_CPP03)
 
+    /// Convert the object
+    /**
+     * If the object can't be converted to T, msgpack::type_error would be thrown.
+     * @tparam T The type of v.
+     * @param v The value you want to get. `v` is output parameter. `v` is overwritten by converted value from the object.
+     * @return The reference of `v`.
+     */
     template <typename T>
     T& convert(T& v) const;
+
+    /// Convert the object (obsolete)
+    /**
+     * If the object can't be converted to T, msgpack::type_error would be thrown.
+     * @tparam T The type of v.
+     * @param v The pointer of the value you want to get. `v` is output parameter. `*v` is overwritten by converted value from the object.
+     * @return The pointer of `v`.
+     */
     template <typename T>
     T* convert(T* v) const;
 
+    /// Convert the object if not nil
+    /**
+     * If the object is not nil and can't be converted to T, msgpack::type_error would be thrown.
+     * @tparam T The type of v.
+     * @param v The value you want to get. `v` is output parameter. `v` is overwritten by converted value from the object if the object is not nil.
+     * @return If the object is nil, then return false, else return true.
+     */
     template <typename T>
     bool convert_if_not_nil(T& v) const;
 
+    /// Default constructor. The object is set to nil.
     object();
 
+    /// Copy constructor. Object is shallow copied.
     object(const msgpack_object& o);
 
+    /// Construct object from T
+    /**
+     * If `v` is the type that is corresponding to MessegePack format str, bin, ext, array, or map,
+     * you need to call `object(const T& v, msgpack::zone& z)` instead of this constructor.
+     *
+     * @tparam T The type of `v`.
+     * @param v The value you want to convert.
+     */
     template <typename T>
     explicit object(const T& v);
 
+    /// Construct object from T
+    /**
+     * The object is constructed on the zone `z`.
+     * See https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_object
+     *
+     * @tparam T The type of `v`.
+     * @param v The value you want to convert.
+     * @param z The zone that is used by the object.
+     */
     template <typename T>
     object(const T& v, msgpack::zone& z);
 
-    // obsolete
+    /// Construct object from T (obsolete)
+    /**
+     * The object is constructed on the zone `z`.
+     * Use `object(const T& v, msgpack::zone& z)` instead of this constructor.
+     * See https://github.com/msgpack/msgpack-c/wiki/v1_1_cpp_object
+     *
+     * @tparam T The type of `v`.
+     * @param v The value you want to convert.
+     * @param z The pointer to the zone that is used by the object.
+     */
     template <typename T>
     object(const T& v, msgpack::zone* z);