You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by we...@apache.org on 2019/06/14 21:48:24 UTC
[arrow] branch master updated: ARROW-5341: [C++][Documentation]
developers/cpp.rst should mention documentation warnings
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 8c5271d ARROW-5341: [C++][Documentation] developers/cpp.rst should mention documentation warnings
8c5271d is described below
commit 8c5271d96649bf68e17d678ceb1057834a9095b3
Author: Benjamin Kietzman <be...@gmail.com>
AuthorDate: Fri Jun 14 16:48:10 2019 -0500
ARROW-5341: [C++][Documentation] developers/cpp.rst should mention documentation warnings
Add a section detailing that documentation warnings will break the build at level `CHECKIN` with the clang compiler. The relevant clang documentation is linked so that readers can look up what might provoke a doc warning
Author: Benjamin Kietzman <be...@gmail.com>
Author: Wes McKinney <we...@apache.org>
Closes #4578 from bkietz/5341-Add-instructions-about-fixing-and-testin and squashes the following commits:
f0c3ed34d <Wes McKinney> Consolidate developer docs related to Doxygen comments in a new subsection
7e155a27a <Benjamin Kietzman> add section describing documentation warnings
---
docs/README.md | 4 ++--
docs/source/developers/cpp.rst | 45 +++++++++++++++++++++++++++---------------
2 files changed, 31 insertions(+), 18 deletions(-)
diff --git a/docs/README.md b/docs/README.md
index aa0a231..2130426 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -23,8 +23,8 @@ This directory contains source files for building the main project
documentation. This includes the [Arrow columnar format specification][2].
Instructions for building the documentation site are found in
-[docs/source/building.rst][1]. The build depends on the API
+[docs/source/developers/documentation.rst][1]. The build depends on the API
documentation for some of the project subcomponents.
[1]: https://github.com/apache/arrow/blob/master/docs/source/developers/documentation.rst
-[2]: https://github.com/apache/arrow/tree/master/docs/source/format
\ No newline at end of file
+[2]: https://github.com/apache/arrow/tree/master/docs/source/format
diff --git a/docs/source/developers/cpp.rst b/docs/source/developers/cpp.rst
index fbc483c..568e5c8 100644
--- a/docs/source/developers/cpp.rst
+++ b/docs/source/developers/cpp.rst
@@ -355,8 +355,6 @@ This project follows `Google's C++ Style Guide
<https://google.github.io/styleguide/cppguide.html>`_ with minor exceptions:
* We relax the line length restriction to 90 characters.
-* We use doxygen style comments ("///") in header files for comments that we
- wish to show up in API documentation
* We use the ``NULLPTR`` macro in header files (instead of ``nullptr``) defined
in ``src/arrow/util/macros.h`` to support building C++/CLI (ARROW-1134)
@@ -368,7 +366,10 @@ codebase is subjected to a number of code style and code cleanliness checks.
In order to have a passing CI build, your modified git branch must pass the
following checks:
-* C++ builds without compiler warnings with ``-DBUILD_WARNING_LEVEL=CHECKIN``
+* C++ builds with the project's active version of ``clang`` without
+ compiler warnings with ``-DBUILD_WARNING_LEVEL=CHECKIN``. Note that
+ there are classes of warnings (such as `-Wdocumentation`, see more
+ on this below) that are not caught by `gcc`.
* C++ unit test suite with valgrind enabled, use ``-DARROW_TEST_MEMCHECK=ON``
when invoking CMake
* Passes cpplint checks, checked with ``make lint``
@@ -400,6 +401,31 @@ target that is executable from the root of the repository:
See :ref:`integration` for more information about the project's
``docker-compose`` configuration.
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+We use Doxygen style comments (``///``) in header files for comments
+that we wish to show up in API documentation for classes and
+functions.
+
+When using ``clang`` and building with
+``-DBUILD_WARNING_LEVEL=CHECKIN``, the ``-Wdocumentation`` flag is
+used which checks for some common documnetation inconsistencies, like
+documenting some, but not all function parameters with ``\param``. See
+the `LLVM documentation warnings section
+<https://releases.llvm.org/7.0.1/tools/clang/docs/DiagnosticsReference.html#wdocumentation>`_
+for more about this.
+
+While we publish the API documentation as part of the main Sphinx-based
+documentation site, you can also build the C++ API documentation anytime using
+Doxygen. Run the following command from the ``cpp/apidoc`` directory:
+
+.. code-block:: shell
+
+ doxygen Doxyfile
+
+This requires `Doxygen <https://www.doxygen.org>`_ to be installed.
+
Modular Build Targets
~~~~~~~~~~~~~~~~~~~~~
@@ -432,19 +458,6 @@ Parquet libraries, its tests, and its dependencies, you can run:
If you omit an explicit target when invoking ``make``, all targets will be
built.
-Building API Documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-While we publish the API documentation as part of the main Sphinx-based
-documentation site, you can also build the C++ API documentation anytime using
-Doxygen. Run the following command from the ``cpp/apidoc`` directory:
-
-.. code-block:: shell
-
- doxygen Doxyfile
-
-This requires `Doxygen <https://www.doxygen.org>`_ to be installed.
-
Benchmarking
~~~~~~~~~~~~