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