From 92bf9d2cf81228b259eda6f166562a7c8536438f Mon Sep 17 00:00:00 2001
From: Alexis Placet <alexis.placet@quantstack.net>
Date: Fri, 19 Apr 2024 11:36:26 +0200
Subject: [PATCH] Add documentation

---
 include/sparrow/c_interface.hpp | 108 +++++++++++++++++++++++++++-----
 test/test_c_data_interface.cpp  |   8 +--
 2 files changed, 98 insertions(+), 18 deletions(-)

diff --git a/include/sparrow/c_interface.hpp b/include/sparrow/c_interface.hpp
index 730eee5e..a82664e3 100644
--- a/include/sparrow/c_interface.hpp
+++ b/include/sparrow/c_interface.hpp
@@ -66,7 +66,14 @@ extern "C"
 
 namespace sparrow
 {
+    /**
+     * Holds the allocator for the buffers of an ArrowArray.
+     * 
+     * @tparam BufferType The type of the buffers.
+     * @tparam Allocator An allocator for BufferType.
+     */
     template <class BufferType, template <typename> class Allocator>
+    requires sparrow::allocator<Allocator<BufferType>>
     struct ArrowArrayPrivateData
     {
         ArrowArrayPrivateData()
@@ -82,7 +89,13 @@ namespace sparrow
         any_allocator<BufferType> buffer_allocator;
     };
 
+    /**
+     * Holds the allocator for the strings of an ArrowSchema. 
+     * 
+     * @tparam Allocator An allocator for char.
+     */
     template <template <typename> class Allocator>
+    requires sparrow::allocator<Allocator<char>>
     struct ArrowSchemaPrivateData
     {
         ArrowSchemaPrivateData()
@@ -101,7 +114,17 @@ namespace sparrow
         size_t metadata_size = 0;
     };
 
-    template <class T>
+    
+    template <typename T>
+    concept ArrowType = std::is_same_v<T, ArrowArray> || std::is_same_v<T, ArrowSchema>;
+    
+    /**
+     * Releases the children and dictionary of an ArrowArray or ArrowSchema.
+     * 
+     * @tparam T The type of the object.
+     * @param obj The object to release the children and dictionary of.
+     */
+    template <ArrowType T>
     void release_children(T& obj)
     {
         for (int64_t i = 0; i < obj.n_children; ++i)
@@ -114,12 +137,18 @@ namespace sparrow
             }
             delete child;
         }
-        delete obj.children;
+        delete[] obj.children;
         obj.children = nullptr;
         obj.n_children = 0;
     }
 
-    template <class T>
+    /**
+     * Releases the dictionary of an ArrowArray or ArrowSchema.
+     * 
+     * @tparam T The type of the object.
+     * @param obj The object to release the dictionary of.
+     */
+    template <ArrowType T>
     void release_dictionary(T& obj)
     {
         if (obj.dictionary != nullptr && obj.dictionary->release != nullptr)
@@ -131,14 +160,28 @@ namespace sparrow
         obj.dictionary = nullptr;
     }
 
-    template <class T>
+    /**
+     * Releases the children and dictionary of an ArrowArray or ArrowSchema.
+     * 
+     * @tparam T The type of the object.
+     * @param obj The object to release the children and dictionary of.
+     */
+    template <ArrowType T>
     void common_deleter(T& obj)
     {
         release_children(obj);
         release_dictionary(obj);
     }
 
+    /**
+     * Deletes an ArrowArray.
+     * 
+     * @tparam T The type of the buffers of the ArrowArray.
+     * @tparam Allocator The allocator for the buffers of the ArrowArray.
+     * @param array The ArrowArray to delete.
+     */
     template <typename T, template <typename> typename Allocator>
+    requires sparrow::allocator<Allocator<T>>
     void delete_array(ArrowArray* array)
     {
         assert(array != nullptr);
@@ -156,15 +199,24 @@ namespace sparrow
         delete array->buffers;
         array->buffers = nullptr;
         array->n_buffers = 0;
-        delete static_cast<ArrowArrayPrivateData<T, Allocator>*>(array->private_data);
+
         array->length = 0;
         array->null_count = 0;
         array->offset = 0;
+
+        delete private_data;
         array->private_data = nullptr;
         array->release = nullptr;
     }
 
+    /**
+     * Deletes an ArrowSchema.
+     *
+     * @tparam Allocator The allocator for the strings of the ArrowSchema.
+     * @param schema The ArrowSchema to delete.
+     */
     template <template <typename> class Allocator>
+    requires sparrow::allocator<Allocator<char>>
     void delete_schema(ArrowSchema* schema)
     {
         assert(schema != nullptr);
@@ -172,12 +224,11 @@ namespace sparrow
 
         common_deleter(*schema);
 
-        using ArrowSchemaPrivateData_with_allocator = ArrowSchemaPrivateData<Allocator>;
-        const auto private_data = static_cast<ArrowSchemaPrivateData_with_allocator*>(schema->private_data);
+        const auto private_data = static_cast<ArrowSchemaPrivateData<Allocator>*>(schema->private_data);
         auto& string_allocator = private_data->string_allocator;
         const auto dealocate_string = [&string_allocator](const char*& str, size_t& size) -> void
         {
-            string_allocator.deallocate(const_cast<char *>(str), size * sizeof(char));
+            string_allocator.deallocate(const_cast<char*>(str), size * sizeof(char));
             str = nullptr;
             size = 0;
         };
@@ -186,16 +237,30 @@ namespace sparrow
         dealocate_string(schema->name, private_data->name_size);
         dealocate_string(schema->metadata, private_data->metadata_size);
 
-        delete static_cast<ArrowSchemaPrivateData<Allocator>*>(schema->private_data);
+        delete private_data;
         schema->n_children = 0;
         schema->flags = 0;
-        
+
         schema->private_data = nullptr;
         schema->release = nullptr;
     }
 
+    /**
+     * Creates an ArrowSchema.
+     *
+     * @tparam Allocator The allocator for the strings of the ArrowSchema.
+     * @param format The format of the schema.
+     * @param name The name of the schema.
+     * @param metadata The metadata of the schema.
+     * @param flags The flags of the schema.
+     * @param n_children The number of children of the schema.
+     * @param children The children of the schema.
+     * @param dictionary The dictionary of the schema.
+     * @return The created ArrowSchema.
+     */
     template <template <typename> class Allocator>
-    ArrowSchema make_schema_constructor(
+    requires sparrow::allocator<Allocator<char>>
+    ArrowSchema make_arrow_schema(
         const char* format,
         const char* name,
         const char* metadata,
@@ -211,11 +276,11 @@ namespace sparrow
 
         auto private_data = static_cast<ArrowSchemaPrivateData<Allocator>*>(schema.private_data);
 
-        const auto build_string = [&private_data](size_t& size, const char* str) -> const char *
+        const auto build_string = [&private_data](size_t& size, const char* str) -> const char*
         {
             size = strlen(str) + 1;
-            const char * dest = private_data->string_allocator.allocate(size);
-            std::uninitialized_copy(str, str + size, const_cast<char *>(dest));
+            const char* dest = private_data->string_allocator.allocate(size);
+            std::uninitialized_copy(str, str + size, const_cast<char*>(dest));
             return dest;
         };
 
@@ -230,7 +295,22 @@ namespace sparrow
         return schema;
     };
 
+    /**
+     * Creates an ArrowArray.
+     *
+     * @tparam T The type of the buffers of the ArrowArray.
+     * @tparam Allocator The allocator for the buffers of the ArrowArray.
+     * @param length The length of the array.
+     * @param null_count The null count of the array.
+     * @param offset The offset of the array.
+     * @param n_buffers The number of buffers of the array.
+     * @param n_children The number of children of the array.
+     * @param children The children of the array.
+     * @param dictionary The dictionary of the array.
+     * @return The created ArrowArray.
+     */
     template <class T, template <typename> class Allocator>
+    requires sparrow::allocator<Allocator<T>>
     ArrowArray make_array_constructor(
         int64_t length,
         int64_t null_count,
diff --git a/test/test_c_data_interface.cpp b/test/test_c_data_interface.cpp
index 50c104d3..8b462423 100644
--- a/test/test_c_data_interface.cpp
+++ b/test/test_c_data_interface.cpp
@@ -48,7 +48,7 @@ TEST_SUITE("ArrowArray")
         children[1] = new ArrowArray;
         auto dictionary = new ArrowArray;
         auto array = sparrow::make_array_constructor<int, std::allocator>(1, 0, 0, 1, 2, children, dictionary);
-        
+
         array.release(&array);
 
         CHECK_EQ(array.length, 0);
@@ -65,14 +65,14 @@ TEST_SUITE("ArrowArray")
 
 TEST_SUITE("ArrowSchema")
 {
-    TEST_CASE("make_schema_constructor")
+    TEST_CASE("make_arrow_schema")
     {
         auto children = new ArrowSchema*[2];
         children[0] = new ArrowSchema;
         children[1] = new ArrowSchema;
         auto dictionary = new ArrowSchema;
 
-        const auto schema = sparrow::make_schema_constructor<std::allocator>(
+        const auto schema = sparrow::make_arrow_schema<std::allocator>(
             "format",
             "name",
             "metadata",
@@ -100,7 +100,7 @@ TEST_SUITE("ArrowSchema")
         children[1] = new ArrowSchema;
         auto dictionary = new ArrowSchema;
 
-        auto schema = sparrow::make_schema_constructor<std::allocator>(
+        auto schema = sparrow::make_arrow_schema<std::allocator>(
             "format",
             "name",
             "metadata",