From 88189f45cc12afe4ad93565decfb6b01edfb961f Mon Sep 17 00:00:00 2001
From: Dewey Dunnington <dewey@fishandwhistle.net>
Date: Fri, 20 Sep 2024 00:43:32 -0500
Subject: [PATCH] document helpers

---
 c/driver/framework/objects.h | 16 ++++++++++++----
 c/driver/framework/utility.h | 25 +++++++++++++++++++++++++
 2 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/c/driver/framework/objects.h b/c/driver/framework/objects.h
index 82d0ea9578..a855265caa 100644
--- a/c/driver/framework/objects.h
+++ b/c/driver/framework/objects.h
@@ -21,14 +21,19 @@
 #include <string_view>
 #include <vector>
 
-#include <nanoarrow/nanoarrow.h>
-
+#include <arrow-adbc/adbc.h>
 #include "driver/framework/status.h"
 #include "driver/framework/type_fwd.h"
 
 namespace adbc::driver {
 
-Status MakeGetObjectsSchema(struct ArrowSchema* schema);
+/// \defgroup adbc-framework-catalog Catalog Utilities
+/// Utilities for implementing catalog/metadata-related functions.
+///
+/// @{
+
+/// \brief Create the ArrowSchema for AdbcConnectionGetObjects().
+Status MakeGetObjectsSchema(ArrowSchema* schema);
 
 /// \brief The GetObjects level.
 enum class GetObjectsDepth {
@@ -39,6 +44,9 @@ enum class GetObjectsDepth {
 };
 
 /// \brief Helper to implement GetObjects.
+///
+/// Drivers can implement methods of the GetObjectsHelper in a driver-specific
+/// class to get a compliant implementation of AdbcConnectionGetObjects().
 struct GetObjectsHelper {
   virtual ~GetObjectsHelper() = default;
 
@@ -136,5 +144,5 @@ Status BuildGetObjects(GetObjectsHelper* helper, GetObjectsDepth depth,
                        std::optional<std::string_view> table_filter,
                        std::optional<std::string_view> column_filter,
                        const std::vector<std::string_view>& table_types,
-                       struct ArrowArrayStream* out);
+                       ArrowArrayStream* out);
 }  // namespace adbc::driver
diff --git a/c/driver/framework/utility.h b/c/driver/framework/utility.h
index 2c52e8a55c..af60594ea4 100644
--- a/c/driver/framework/utility.h
+++ b/c/driver/framework/utility.h
@@ -27,13 +27,34 @@
 
 namespace adbc::driver {
 
+/// \brief Create an ArrowArrayStream with zero batches from a given ArrowSchema.
+/// \ingroup adbc-framework-catalog
+///
+/// This function takes ownership of schema; the caller is responsible for
+/// releasing out.
 void MakeEmptyStream(ArrowSchema* schema, ArrowArrayStream* out);
 
+/// \brief Create an ArrowArrayStream from a given ArrowSchema and ArrowArray.
+/// \ingroup adbc-framework-catalog
+///
+/// The resulting ArrowArrayStream will contain zero batches if the length of the
+/// array is zero, or exactly one batch if the length of the array is non-zero.
+/// This function takes ownership of schema and array; the caller is responsible for
+/// releasing out.
 void MakeArrayStream(ArrowSchema* schema, ArrowArray* array, ArrowArrayStream* out);
 
+/// \brief Create an ArrowArrayStream representation of a vector of table types.
+/// \ingroup adbc-framework-catalog
+///
+/// Create an ArrowArrayStream representation of an array of table types
+/// that can be used to implement AdbcConnectionGetTableTypes(). The caller is responsible
+/// for releasing out on success.
 Status MakeTableTypesStream(const std::vector<std::string>& table_types,
                             ArrowArrayStream* out);
 
+/// \brief Representation of a single item in an array to be returned
+/// from AdbcConnectionGetInfo().
+/// \ingroup adbc-framework-catalog
 struct InfoValue {
   uint32_t code;
   std::variant<std::string, int64_t> value;
@@ -43,6 +64,10 @@ struct InfoValue {
   InfoValue(uint32_t code, const char* value) : InfoValue(code, std::string(value)) {}
 };
 
+/// \brief Create an ArrowArrayStream to be returned from AdbcConnectionGetInfo().
+/// \ingroup adbc-framework-catalog
+///
+/// The caller is responsible for releasing out on success.
 Status MakeGetInfoStream(const std::vector<InfoValue>& infos, ArrowArrayStream* out);
 
 }  // namespace adbc::driver