From 1c9a3122c603e2766a793766a11ff4c706efb2aa Mon Sep 17 00:00:00 2001
From: Vyas Ramasubramani <vyasr@nvidia.com>
Date: Thu, 7 Mar 2024 05:24:15 -0800
Subject: [PATCH] GH-40318: [C++][Docs] Add documentation of array factories
 (#40373)

### Rationale for this change

These factory functions are generally useful and available, so documenting them helps external users find them without having to search the source code.

### What changes are included in this PR?

This PR adds the array factories in arrow/array/util.h into a doxygen group for array factories and adds that group to the Sphinx C++ API documentation.

### Are these changes tested?

I built the docs locally to verify.

### Are there any user-facing changes?

Nothing to the API, only docs.

* GitHub Issue: #40318

Authored-by: Vyas Ramasubramani <vyasr@nvidia.com>
Signed-off-by: Antoine Pitrou <antoine@python.org>
---
 cpp/src/arrow/array/util.h    | 6 ++++++
 docs/source/cpp/api/array.rst | 8 +++++++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/cpp/src/arrow/array/util.h b/cpp/src/arrow/array/util.h
index 9f34af0525d96..fd8e75ddb8640 100644
--- a/cpp/src/arrow/array/util.h
+++ b/cpp/src/arrow/array/util.h
@@ -31,6 +31,10 @@
 
 namespace arrow {
 
+/// \defgroup array-factories Array factory functions
+///
+/// @{
+
 /// \brief Create a strongly-typed Array instance from generic ArrayData
 /// \param[in] data the array contents
 /// \return the resulting Array instance
@@ -65,6 +69,8 @@ ARROW_EXPORT
 Result<std::shared_ptr<Array>> MakeEmptyArray(std::shared_ptr<DataType> type,
                                               MemoryPool* pool = default_memory_pool());
 
+/// @}
+
 namespace internal {
 
 /// \brief Swap endian of each element in a generic ArrayData
diff --git a/docs/source/cpp/api/array.rst b/docs/source/cpp/api/array.rst
index eca9ec398c15a..a7e5d0cf07e0a 100644
--- a/docs/source/cpp/api/array.rst
+++ b/docs/source/cpp/api/array.rst
@@ -27,6 +27,12 @@ Arrays
    :project: arrow_cpp
    :members:
 
+Factory functions
+=================
+
+.. doxygengroup:: array-factories
+   :content-only:
+
 Concrete array subclasses
 =========================
 
@@ -86,4 +92,4 @@ Utilities
 .. doxygenclass:: arrow::ArrayVisitor
    :project: arrow_cpp
    :members:
-   :undoc-members:
\ No newline at end of file
+   :undoc-members: