cpp: adds Doxyfile

cpp/Makefile.am

@@ -11,3 +11,9 @@ DOC_FILES = \
 EXTRA_DIST = \
 		$(DOC_FILES)
 
+doxygen:
+	./preprocess
+	./preprocess clean
+	cd src && $(MAKE) doxygen
+	./preprocess
+

cpp/preprocess

@@ -6,6 +6,7 @@ preprocess() {
 		echo ""
 		echo "** preprocess failed **"
 		echo ""
+		exit 1
 	else
 		mv $1.tmp $1
 	fi

cpp/src/Makefile.am

@@ -73,3 +73,20 @@ EXTRA_DIST = \
 		msgpack/type/define.hpp.erb \
 		msgpack/type/tuple.hpp.erb
 
+
+doxygen_c:
+	cat ../Doxyfile > Doxyfile_c
+	echo "FILE_PATTERNS      = *.h" >> Doxyfile_c
+	echo "OUTPUT_DIRECTORY   = doc_c" >> Doxyfile_c
+	echo "PROJECT_NAME       = \"MessagePack for C\"" >> Doxyfile_c
+	doxygen Doxyfile_c
+
+doxygen_cpp:
+	cat ../Doxyfile > Doxyfile_cpp
+	echo "FILE_PATTERNS      = *.hpp" >> Doxyfile_cpp
+	echo "OUTPUT_DIRECTORY   = doc_cpp" >> Doxyfile_cpp
+	echo "PROJECT_NAME       = \"MessagePack for C++\"" >> Doxyfile_cpp
+	doxygen Doxyfile_cpp
+
+doxygen: doxygen_c doxygen_cpp
+

cpp/src/msgpack.h

@@ -15,6 +15,11 @@
  *    See the License for the specific language governing permissions and
  *    limitations under the License.
  */
+/**
+ * @defgroup msgpack MessagePack C
+ * @{
+ * @}
+ */
 #include "msgpack/object.h"
 #include "msgpack/zone.h"
 #include "msgpack/pack.h"

cpp/src/msgpack/object.h

@@ -26,6 +26,12 @@ extern "C" {
 #endif
 
 
+/**
+ * @defgroup msgpack_object Dynamically typed object
+ * @ingroup msgpack
+ * @{
+ */
+
 typedef enum {
 	MSGPACK_OBJECT_NIL					= 0x00,
 	MSGPACK_OBJECT_BOOLEAN				= 0x01,
@@ -81,6 +87,8 @@ void msgpack_object_print(FILE* out, msgpack_object o);
 
 bool msgpack_object_equal(const msgpack_object x, const msgpack_object y);
 
+/** @} */
+
 
 #ifdef __cplusplus
 }

cpp/src/msgpack/pack.h

@@ -27,6 +27,19 @@ extern "C" {
 #endif
 
 
+/**
+ * @defgroup msgpack_buffer Buffers
+ * @ingroup msgpack
+ * @{
+ * @}
+ */
+
+/**
+ * @defgroup msgpack_pack Serializer
+ * @ingroup msgpack
+ * @{
+ */
+
 typedef int (*msgpack_packer_write)(void* data, const char* buf, unsigned int len);
 
 typedef struct msgpack_packer {
@@ -74,6 +87,8 @@ static int msgpack_pack_raw_body(msgpack_packer* pk, const void* b, size_t l);
 int msgpack_pack_object(msgpack_packer* pk, msgpack_object d);
 
 
+/** @} */
+
 
 #define msgpack_pack_inline_func(name) \
 	inline int msgpack_pack ## name

cpp/src/msgpack/sbuffer.h

@@ -21,15 +21,17 @@
 #include <stdlib.h>
 #include <string.h>
 
-#ifndef MSGPACK_SBUFFER_INIT_SIZE
-#define MSGPACK_SBUFFER_INIT_SIZE 8192
-#endif
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 
+/**
+ * @defgroup msgpack_sbuffer Simple buffer
+ * @ingroup msgpack_buffer
+ * @{
+ */
+
 typedef struct msgpack_sbuffer {
 	size_t size;
 	char* data;
@@ -58,6 +60,10 @@ static inline void msgpack_sbuffer_free(msgpack_sbuffer* sbuf)
 	free(sbuf);
 }
 
+#ifndef MSGPACK_SBUFFER_INIT_SIZE
+#define MSGPACK_SBUFFER_INIT_SIZE 8192
+#endif
+
 static inline int msgpack_sbuffer_write(void* data, const char* buf, unsigned int len)
 {
 	msgpack_sbuffer* sbuf = (msgpack_sbuffer*)data;
@@ -94,6 +100,9 @@ static inline void msgpack_sbuffer_clear(msgpack_sbuffer* sbuf)
 	sbuf->size = 0;
 }
 
+/** @} */
+
+
 #ifdef __cplusplus
 }
 #endif

cpp/src/msgpack/unpack.h

@@ -22,19 +22,34 @@
 #include "msgpack/object.h"
 #include <string.h>
 
-#ifndef MSGPACK_UNPACKER_INIT_BUFFER_SIZE
-#define MSGPACK_UNPACKER_INIT_BUFFER_SIZE (64*1024)
-#endif
-
-#ifndef MSGPACK_UNPACKER_RESERVE_SIZE
-#define MSGPACK_UNPACKER_RESERVE_SIZE (32*1024)
-#endif
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 
+/**
+ * @defgroup msgpack_unpack Deserializer
+ * @ingroup msgpack
+ * @{
+ */
+
+typedef struct msgpack_unpacked {
+	msgpack_zone* zone;
+	msgpack_object data;
+} msgpack_unpacked;
+
+bool msgpack_unpack_next(msgpack_unpacked* result,
+		const char* data, size_t len, size_t* off);
+
+/** @} */
+
+
+/**
+ * @defgroup msgpack_unpacker Streaming deserializer
+ * @ingroup msgpack
+ * @{
+ */
+
 typedef struct msgpack_unpacker {
 	char* buffer;
 	size_t used;
@@ -46,27 +61,100 @@ typedef struct msgpack_unpacker {
 	void* ctx;
 } msgpack_unpacker;
 
-typedef struct msgpack_unpacked {
-	msgpack_zone* zone;
-	msgpack_object data;
-} msgpack_unpacked;
 
+#ifndef MSGPACK_UNPACKER_INIT_BUFFER_SIZE
+#define MSGPACK_UNPACKER_INIT_BUFFER_SIZE (64*1024)
+#endif
+
+/**
+ * Initializes a streaming deserializer.
+ * The initialized deserializer must be destroyed by msgpack_unpacker_destroy(msgpack_unpacker*).
+ */
 bool msgpack_unpacker_init(msgpack_unpacker* mpac, size_t initial_buffer_size);
+
+/**
+ * Destroys a streaming deserializer initialized by msgpack_unpacker_init(msgpack_unpacker*, size_t).
+ */
 void msgpack_unpacker_destroy(msgpack_unpacker* mpac);
 
+
+/**
+ * Creates a streaming deserializer.
+ * The created deserializer must be destroyed by msgpack_unpacker_free(msgpack_unpacker*).
+ */
 msgpack_unpacker* msgpack_unpacker_new(size_t initial_buffer_size);
+
+/**
+ * Frees a streaming deserializer created by msgpack_unpacker_new(size_t).
+ */
 void msgpack_unpacker_free(msgpack_unpacker* mpac);
 
+
+#ifndef MSGPACK_UNPACKER_RESERVE_SIZE
+#define MSGPACK_UNPACKER_RESERVE_SIZE (32*1024)
+#endif
+
+/**
+ * Reserves free space of the internal buffer.
+ * Use this function to fill the internal buffer with
+ * msgpack_unpacker_buffer(msgpack_unpacker*),
+ * msgpack_unpacker_buffer_capacity(const msgpack_unpacker*) and
+ * msgpack_unpacker_buffer_consumed(msgpack_unpacker*).
+ */
 static inline bool   msgpack_unpacker_reserve_buffer(msgpack_unpacker* mpac, size_t size);
+
+/**
+ * Gets pointer to the free space of the internal buffer.
+ * Use this function to fill the internal buffer with
+ * msgpack_unpacker_reserve_buffer(msgpack_unpacker*, size_t),
+ * msgpack_unpacker_buffer_capacity(const msgpack_unpacker*) and
+ * msgpack_unpacker_buffer_consumed(msgpack_unpacker*).
+ */
 static inline char*  msgpack_unpacker_buffer(msgpack_unpacker* mpac);
+
+/**
+ * Gets size of the free space of the internal buffer.
+ * Use this function to fill the internal buffer with
+ * msgpack_unpacker_reserve_buffer(msgpack_unpacker*, size_t),
+ * msgpack_unpacker_buffer(const msgpack_unpacker*) and
+ * msgpack_unpacker_buffer_consumed(msgpack_unpacker*).
+ */
 static inline size_t msgpack_unpacker_buffer_capacity(const msgpack_unpacker* mpac);
+
+/**
+ * Notifies the deserializer that the internal buffer filled.
+ * Use this function to fill the internal buffer with
+ * msgpack_unpacker_reserve_buffer(msgpack_unpacker*, size_t),
+ * msgpack_unpacker_buffer(msgpack_unpacker*) and
+ * msgpack_unpacker_buffer_capacity(const msgpack_unpacker*).
+ */
 static inline void   msgpack_unpacker_buffer_consumed(msgpack_unpacker* mpac, size_t size);
 
+
+/**
+ * Deserializes one object.
+ * Returns true if it successes. Otherwise false is returned.
+ * @param pac  pointer to an initialized msgpack_unpacked object.
+ */
 bool msgpack_unpacker_next(msgpack_unpacker* mpac, msgpack_unpacked* pac);
 
+/**
+ * Initializes a msgpack_unpacked object.
+ * The initialized object must be destroyed by msgpack_unpacked_destroy(msgpack_unpacker*).
+ * Use the object with msgpack_unpacker_next(msgpack_unpacker*, msgpack_unpacked*) or
+ * msgpack_unpack_next(msgpack_unpacked*, const char*, size_t, size_t*).
+ */
 static inline void msgpack_unpacked_init(msgpack_unpacked* result);
+
+/**
+ * Destroys a streaming deserializer initialized by msgpack_unpacked().
+ */
 static inline void msgpack_unpacked_destroy(msgpack_unpacked* result);
 
+/**
+ * Releases the memory zone from msgpack_unpacked object.
+ * The released zone must be freed by msgpack_zone_free(msgpack_zone*).
+ */
 static inline msgpack_zone* msgpack_unpacked_release_zone(msgpack_unpacked* result);
 
 
@@ -83,10 +171,10 @@ void msgpack_unpacker_reset(msgpack_unpacker* mpac);
 static inline size_t msgpack_unpacker_message_size(const msgpack_unpacker* mpac);
 
 
-bool msgpack_unpack_next(msgpack_unpacked* result,
+/** @} */
-		const char* data, size_t len, size_t* off);
 
 
+// obsolete
 typedef enum {
 	MSGPACK_UNPACK_SUCCESS				=  2,
 	MSGPACK_UNPACK_EXTRA_BYTES			=  1,
@@ -94,6 +182,7 @@ typedef enum {
 	MSGPACK_UNPACK_PARSE_ERROR			= -1,
 } msgpack_unpack_return;
 
+// obsolete
 msgpack_unpack_return
 msgpack_unpack(const char* data, size_t len, size_t* off,
 		msgpack_zone* result_zone, msgpack_object* result);

cpp/src/msgpack/vrefbuffer.h

@@ -30,19 +30,17 @@ struct iovec {
 };
 #endif
 
-#ifndef MSGPACK_VREFBUFFER_REF_SIZE
-#define MSGPACK_VREFBUFFER_REF_SIZE 32
-#endif
-
-#ifndef MSGPACK_VREFBUFFER_CHUNK_SIZE
-#define MSGPACK_VREFBUFFER_CHUNK_SIZE 8192
-#endif
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 
+/**
+ * @defgroup msgpack_vrefbuffer Vectored Referencing buffer
+ * @ingroup msgpack_buffer
+ * @{
+ */
+
 struct msgpack_vrefbuffer_chunk;
 typedef struct msgpack_vrefbuffer_chunk msgpack_vrefbuffer_chunk;
 
@@ -64,6 +62,14 @@ typedef struct msgpack_vrefbuffer {
 } msgpack_vrefbuffer;
 
 
+#ifndef MSGPACK_VREFBUFFER_REF_SIZE
+#define MSGPACK_VREFBUFFER_REF_SIZE 32
+#endif
+
+#ifndef MSGPACK_VREFBUFFER_CHUNK_SIZE
+#define MSGPACK_VREFBUFFER_CHUNK_SIZE 8192
+#endif
+
 bool msgpack_vrefbuffer_init(msgpack_vrefbuffer* vbuf,
 		size_t ref_size, size_t chunk_size);
 void msgpack_vrefbuffer_destroy(msgpack_vrefbuffer* vbuf);
@@ -86,6 +92,8 @@ int msgpack_vrefbuffer_migrate(msgpack_vrefbuffer* vbuf, msgpack_vrefbuffer* to)
 
 void msgpack_vrefbuffer_clear(msgpack_vrefbuffer* vref);
 
+/** @} */
+
 
 msgpack_vrefbuffer* msgpack_vrefbuffer_new(size_t ref_size, size_t chunk_size)
 {

cpp/src/msgpack/zbuffer.h

@@ -23,25 +23,26 @@
 #include <string.h>
 #include <zlib.h>
 
-#ifndef MSGPACK_ZBUFFER_INIT_SIZE
-#define MSGPACK_ZBUFFER_INIT_SIZE 8192
-#endif
-
-#ifndef MSGPACK_ZBUFFER_RESERVE_SIZE
-#define MSGPACK_ZBUFFER_RESERVE_SIZE 512
-#endif
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 
+/**
+ * @defgroup msgpack_zbuffer Compressed buffer
+ * @ingroup msgpack_buffer
+ * @{
+ */
+
 typedef struct msgpack_zbuffer {
 	z_stream stream;
 	char* data;
 	size_t init_size;
 } msgpack_zbuffer;
 
+#ifndef MSGPACK_ZBUFFER_INIT_SIZE
+#define MSGPACK_ZBUFFER_INIT_SIZE 8192
+#endif
 
 static inline bool msgpack_zbuffer_init(msgpack_zbuffer* zbuf,
 		int level, size_t init_size);
@@ -60,6 +61,10 @@ static inline void msgpack_zbuffer_reset_buffer(msgpack_zbuffer* zbuf);
 static inline char* msgpack_zbuffer_release_buffer(msgpack_zbuffer* zbuf);
 
 
+#ifndef MSGPACK_ZBUFFER_RESERVE_SIZE
+#define MSGPACK_ZBUFFER_RESERVE_SIZE 512
+#endif
+
 static inline int msgpack_zbuffer_write(void* data, const char* buf, unsigned int len);
 
 static inline bool msgpack_zbuffer_expand(msgpack_zbuffer* zbuf);
@@ -191,6 +196,8 @@ char* msgpack_zbuffer_release_buffer(msgpack_zbuffer* zbuf)
 	return tmp;
 }
 
+/** @} */
+
 
 #ifdef __cplusplus
 }

cpp/src/msgpack/zone.h

@@ -25,6 +25,12 @@ extern "C" {
 #endif
 
 
+/**
+ * @defgroup msgpack_zone Memory zone
+ * @ingroup msgpack
+ * @{
+ */
+
 typedef struct msgpack_zone_finalizer {
 	void (*func)(void* data);
 	void* data;
@@ -71,6 +77,7 @@ bool msgpack_zone_is_empty(msgpack_zone* zone);
 
 void msgpack_zone_clear(msgpack_zone* zone);
 
+/** @} */
 
 
 #ifndef MSGPACK_ZONE_ALIGN