Added doxygen docs for alloc.h

include/criterion/alloc.h

@@ -35,9 +35,55 @@ using std::size_t;
 
 CR_BEGIN_C_API
 
+/**
+ *  Allocates a block of memory usable by the test.
+ *
+ *  It is undefined behaviour to access a pointer returned by malloc(3)
+ *  inside a test or its setup and teardown functions; cr_malloc must
+ *  be use in its place for this purpose.
+ *
+ *  This function is semantically identical to malloc(3).
+ *
+ *  @param[in] size The minimal size in bytes of the newly allocated memory.
+ *  @returns The pointer to the start of the allocated memory.
+ */
 CR_API void *cr_malloc(size_t size);
+
+/**
+ *  Allocates and zero-initialize a block of memory usable by the test.
+ *
+ *  It is undefined behaviour to access a pointer returned by calloc(3)
+ *  inside a test or its setup and teardown functions; cr_calloc must
+ *  be use in its place for this purpose.
+ *
+ *  This function is semantically identical to calloc(3).
+ *
+ *  @param[in] nmemb The number of elements to allocate
+ *  @param[in] size The minimal size of each element.
+ *  @returns The pointer to the start of the allocated memory.
+ */
 CR_API void *cr_calloc(size_t nmemb, size_t size);
+
+/**
+ *  Reallocates a block of memory usable by the test.
+ *
+ *  It is undefined behaviour to access a pointer returned by realloc(3)
+ *  inside a test or its setup and teardown functions; cr_realloc must
+ *  be used in its place for this purpose.
+ *
+ *  This function is semantically identical to realloc(3).
+ *
+ *  @param[in] ptr A pointer to the memory that needs to be resized.
+ *  @param[in] size The minimal size of the reallocated memory.
+ *  @returns The pointer to the start of the reallocated memory.
+ */
 CR_API void *cr_realloc(void *ptr, size_t size);
+
+/**
+ *  Free a block of memory allocated by cr_malloc, cr_free or cr_realloc.
+ *
+ *  @param[in] ptr A pointer to the memory that needs to be freed.
+ */
 CR_API void cr_free(void *ptr);
 
 CR_END_C_API
@@ -52,6 +98,19 @@ namespace criterion {
     void *(*const calloc)(size_t, size_t)   = cr_calloc;
     void *(*const realloc)(void *, size_t)  = cr_realloc;
 
+    /**
+     *  Allocates and construct a new object.
+     *
+     *  It is undefined behaviour to access a pointer returned by the new
+     *  operator inside a test or its setup and teardown functions;
+     *  new_obj must be used in its place for this purpose.
+     *
+     *  This function is semantically identical to the new operator.
+     *
+     *  @tparam T The type of the object to construct
+     *  @param[in] params The constructor parameters of T.
+     *  @returns The pointer to the newly constructed object.
+     */
     template<typename T, typename... Params>
     T* new_obj(Params... params) {
         T* obj = static_cast<T*>(cr_malloc(sizeof (T)));
@@ -59,6 +118,19 @@ namespace criterion {
         return obj;
     }
 
+    /**
+     *  Allocates and construct a new array of primitive types
+     *
+     *  It is undefined behaviour to access a pointer returned by the new[]
+     *  operator inside a test or its setup and teardown functions;
+     *  new_arr must be used in its place for this purpose.
+     *
+     *  This function is semantically identical to the new[] operator.
+     *
+     *  @tparam T The compound type of the array to construct
+     *  @param[in] len The length of the array.
+     *  @returns The pointer to the newly constructed array.
+     */
     template<typename T>
     typename std::enable_if<std::is_fundamental<T>::value>::type*
     new_arr(size_t len) {
@@ -68,6 +140,19 @@ namespace criterion {
         return arr;
     }
 
+    /**
+     *  Allocates and construct a new array of object types
+     *
+     *  It is undefined behaviour to access a pointer returned by the new[]
+     *  operator inside a test or its setup and teardown functions;
+     *  new_arr must be used in its place for this purpose.
+     *
+     *  This function is semantically identical to the new[] operator.
+     *
+     *  @tparam T The compound type of the array to construct
+     *  @param[in] len The length of the array.
+     *  @returns The pointer to the newly constructed array.
+     */
     template<typename T>
     T* new_arr(size_t len) {
         void *ptr = cr_malloc(sizeof (size_t) + sizeof (T) * len);
@@ -79,17 +164,41 @@ namespace criterion {
         return arr;
     }
 
+    /**
+     *  Destroys and frees an object allocated by new_obj.
+     *
+     *  This function is semantically identical to the delete operator.
+     *
+     *  @tparam T The type of the object to construct
+     *  @param[in] ptr The object to destroy.
+     */
     template<typename T>
     void delete_obj(T* ptr) {
         ptr->~T();
         cr_free(ptr);
     }
 
+    /**
+     *  Destroys and frees an array allocated by delete_arr.
+     *
+     *  This function is semantically identical to the delete[] operator.
+     *
+     *  @tparam T The type of the object to construct
+     *  @param[in] ptr The object to destroy.
+     */
     template<typename T>
     void delete_arr(typename std::enable_if<std::is_fundamental<T>::value>::type* ptr) {
         cr_free(ptr);
     }
 
+    /**
+     *  Destroys and frees an array allocated by delete_arr.
+     *
+     *  This function is semantically identical to the delete[] operator.
+     *
+     *  @tparam T The type of the object to construct
+     *  @param[in] ptr The object to destroy.
+     */
     template<typename T>
     void delete_arr(T* ptr) {
         size_t *ptr_ = reinterpret_cast<size_t*>(ptr);
@@ -100,6 +209,13 @@ namespace criterion {
         cr_free(ptr_ - 1);
     }
 
+    /**
+     *  Allocator for use in the STL.
+     *
+     *  This internally uses calls to the cr_malloc function family, which
+     *  means that STL collections can be safely used inside tests or
+     *  setup/teardown functions if this allocator is used.
+     */
     template<typename T>
     struct allocator {
         typedef T value_type;