This is an automated email from the ASF dual-hosted git repository.
wesm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new 1f42ac0 ARROW-9428: [C++][Doc] Update buffer allocation documentation
1f42ac0 is described below
commit 1f42ac0ff0bc1ac098cd64ba27c354890c5b8ff4
Author: Antoine Pitrou <anto...@python.org>
AuthorDate: Mon Jul 13 12:27:20 2020 -0500
ARROW-9428: [C++][Doc] Update buffer allocation documentation
Use Result-returning AllocateBuffer() version in example.
Also improve cross-referencing in some places.
Closes #7731 from pitrou/ARROW-9428-buffer-allocation-doc
Authored-by: Antoine Pitrou <anto...@python.org>
Signed-off-by: Wes McKinney <w...@apache.org>
---
docs/source/cpp/api/formats.rst | 6 ++++++
docs/source/cpp/api/support.rst | 11 +++++++++++
docs/source/cpp/arrays.rst | 3 +++
docs/source/cpp/conventions.rst | 3 +++
docs/source/cpp/csv.rst | 3 +++
docs/source/cpp/datatypes.rst | 3 +++
docs/source/cpp/io.rst | 4 +++-
docs/source/cpp/json.rst | 3 +++
docs/source/cpp/memory.rst | 10 +++++++---
docs/source/cpp/parquet.rst | 3 +++
docs/source/cpp/tables.rst | 3 +++
11 files changed, 48 insertions(+), 4 deletions(-)
diff --git a/docs/source/cpp/api/formats.rst b/docs/source/cpp/api/formats.rst
index 75dfb00..a072f11 100644
--- a/docs/source/cpp/api/formats.rst
+++ b/docs/source/cpp/api/formats.rst
@@ -19,6 +19,8 @@
File Formats
============
+.. _cpp-api-csv:
+
CSV
===
@@ -34,6 +36,8 @@ CSV
.. doxygenclass:: arrow::csv::TableReader
:members:
+.. _cpp-api-json:
+
Line-separated JSON
===================
@@ -48,6 +52,8 @@ Line-separated JSON
.. doxygenclass:: arrow::json::TableReader
:members:
+.. _cpp-api-parquet:
+
Parquet reader
==============
diff --git a/docs/source/cpp/api/support.rst b/docs/source/cpp/api/support.rst
index 1547a20..c3310e5 100644
--- a/docs/source/cpp/api/support.rst
+++ b/docs/source/cpp/api/support.rst
@@ -15,9 +15,20 @@
.. specific language governing permissions and limitations
.. under the License.
+===================
Programming Support
===================
+General information
+-------------------
+
+.. doxygenfunction:: arrow::GetBuildInfo
+ :project: arrow_cpp
+
+.. doxygenstruct:: arrow::BuildInfo
+ :project: arrow_cpp
+ :members:
+
Error return and reporting
--------------------------
diff --git a/docs/source/cpp/arrays.rst b/docs/source/cpp/arrays.rst
index 43ac414..bd6ba64 100644
--- a/docs/source/cpp/arrays.rst
+++ b/docs/source/cpp/arrays.rst
@@ -22,6 +22,9 @@
Arrays
======
+.. seealso::
+ :doc:`Array API reference <api/array>`
+
The central type in Arrow is the class :class:`arrow::Array`. An array
represents a known-length sequence of values all having the same type.
Internally, those values are represented by one or several buffers, the
diff --git a/docs/source/cpp/conventions.rst b/docs/source/cpp/conventions.rst
index 33f0a8c..218d028 100644
--- a/docs/source/cpp/conventions.rst
+++ b/docs/source/cpp/conventions.rst
@@ -102,3 +102,6 @@ For example::
// return success at the end
return Status::OK();
}
+
+.. seealso::
+ :doc:`API reference for error reporting <api/support>`
diff --git a/docs/source/cpp/csv.rst b/docs/source/cpp/csv.rst
index 8d37b29..50a5cdb 100644
--- a/docs/source/cpp/csv.rst
+++ b/docs/source/cpp/csv.rst
@@ -27,6 +27,9 @@ Reading CSV files
Arrow provides a fast CSV reader allowing ingestion of external data
as Arrow tables.
+.. seealso::
+ :ref:`CSV reader API reference <cpp-api-csv>`.
+
Basic usage
===========
diff --git a/docs/source/cpp/datatypes.rst b/docs/source/cpp/datatypes.rst
index c411632..9149420 100644
--- a/docs/source/cpp/datatypes.rst
+++ b/docs/source/cpp/datatypes.rst
@@ -21,6 +21,9 @@
Data Types
==========
+.. seealso::
+ :doc:`Datatype API reference <api/datatype>`.
+
Data types govern how physical data is interpreted. Their :ref:`specification
<format_columnar>` allows binary interoperability between different Arrow
implementations, including from different programming languages and runtimes
diff --git a/docs/source/cpp/io.rst b/docs/source/cpp/io.rst
index ed357c6..501998b 100644
--- a/docs/source/cpp/io.rst
+++ b/docs/source/cpp/io.rst
@@ -17,6 +17,7 @@
.. default-domain:: cpp
.. highlight:: cpp
+.. cpp:namespace:: arrow::io
==============================
Input / output and filesystems
@@ -27,7 +28,8 @@ of input / output operations. They operate on streams of
untyped binary data.
Those abstractions are used for various purposes such as reading CSV or
Parquet data, transmitting IPC streams, and more.
-.. cpp:namespace:: arrow::io
+.. seealso::
+ :doc:`API reference for input/output facilities <api/io>`.
Reading binary data
===================
diff --git a/docs/source/cpp/json.rst b/docs/source/cpp/json.rst
index 93dcdfa..cdb742e 100644
--- a/docs/source/cpp/json.rst
+++ b/docs/source/cpp/json.rst
@@ -28,6 +28,9 @@ Arrow allows reading line-separated JSON files as Arrow
tables. Each
independent JSON object in the input file is converted to a row in
the target Arrow table.
+.. seealso::
+ :ref:`JSON reader API reference <cpp-api-json>`.
+
Basic usage
===========
diff --git a/docs/source/cpp/memory.rst b/docs/source/cpp/memory.rst
index 34ef3d1..4eb62ee 100644
--- a/docs/source/cpp/memory.rst
+++ b/docs/source/cpp/memory.rst
@@ -22,6 +22,9 @@
Memory Management
=================
+.. seealso::
+ :doc:`Memory management API reference <api/memory>`
+
Buffers
=======
@@ -71,11 +74,12 @@ You can allocate a buffer yourself by calling one of the
:func:`arrow::AllocateBuffer` or :func:`arrow::AllocateResizableBuffer`
overloads::
- std::shared_ptr<arrow::Buffer> buffer;
-
- if (!arrow::AllocateBuffer(4096, &buffer).ok()) {
+ arrow::Result<std::unique_ptr<Buffer>> maybe_buffer =
arrow::AllocateBuffer(4096);
+ if (!maybe_buffer.ok()) {
// ... handle allocation error
}
+
+ std::shared_ptr<arrow::Buffer> buffer = *std::move(maybe_buffer);
uint8_t* buffer_data = buffer->mutable_data();
memcpy(buffer_data, "hello world", 11);
diff --git a/docs/source/cpp/parquet.rst b/docs/source/cpp/parquet.rst
index 19b3dfd..3c1396d 100644
--- a/docs/source/cpp/parquet.rst
+++ b/docs/source/cpp/parquet.rst
@@ -24,6 +24,9 @@
Reading and writing Parquet files
=================================
+.. seealso::
+ :ref:`Parquet reader and writer API reference <cpp-api-parquet>`.
+
The Parquet C++ library is part of the Apache Arrow project and benefits
from tight integration with Arrow C++.
diff --git a/docs/source/cpp/tables.rst b/docs/source/cpp/tables.rst
index c53d441..ea91987 100644
--- a/docs/source/cpp/tables.rst
+++ b/docs/source/cpp/tables.rst
@@ -22,6 +22,9 @@
Tabular Data
============
+.. seealso::
+ :doc:`Table and RecordBatch API reference <api/table>`.
+
While arrays and chunked arrays represent a one-dimensional sequence of
homogeneous values, data often comes in the form of two-dimensional sets of
heterogeneous data (such as database tables, CSV files...). Arrow provides
