Expand docs for a few modules
- Add missing README.md for a few modules.
- Start or expand docs.rst.
Change-Id: Ic13c5f71f02259205ba990c93e0403d43f7b44b1
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index 742314d..70eee10 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -36,6 +36,9 @@
"$dir_pw_dumb_io_baremetal_stm32f429:docs",
"$dir_pw_dumb_io_stdio:docs",
"$dir_pw_preprocessor:docs",
+ "$dir_pw_presubmit:docs",
+ "$dir_pw_span:docs",
+ "$dir_pw_status:docs",
"$dir_pw_string:docs",
"$dir_pw_test_server:docs",
]
diff --git a/docs/modules.rst b/docs/modules.rst
index 09f69ac..4bf4bc1 100644
--- a/docs/modules.rst
+++ b/docs/modules.rst
@@ -11,5 +11,8 @@
pw_dumb_io_baremetal_stm32f429/docs
pw_dumb_io_stdio/docs
pw_preprocessor/docs
+ pw_presubmit/docs
+ pw_span/docs
+ pw_status/docs
pw_string/docs
pw_test_server/docs
diff --git a/modules.gni b/modules.gni
index 16c6a2e..76d5de2 100644
--- a/modules.gni
+++ b/modules.gni
@@ -30,6 +30,7 @@
"$dir_pigweed/pw_dumb_io_baremetal_stm32f429"
dir_pw_dumb_io_stdio = "$dir_pigweed/pw_dumb_io_stdio"
dir_pw_preprocessor = "$dir_pigweed/pw_preprocessor"
+dir_pw_presubmit = "$dir_pigweed/pw_presubmit"
dir_pw_span = "$dir_pigweed/pw_span"
dir_pw_status = "$dir_pigweed/pw_status"
dir_pw_string = "$dir_pigweed/pw_string"
diff --git a/pw_preprocessor/docs.rst b/pw_preprocessor/docs.rst
index 048abb3..ae08b13 100644
--- a/pw_preprocessor/docs.rst
+++ b/pw_preprocessor/docs.rst
@@ -1,4 +1,4 @@
-.. _chapter-preprocessor:
+.. _chapter-pw-preprocessor:
.. default-domain:: cpp
@@ -13,10 +13,6 @@
=============
C and C++
-Dependencies
-============
-This module has no dependencies.
-
Headers
=======
The preprocessor module provides several headers.
diff --git a/pw_presubmit/BUILD.gn b/pw_presubmit/BUILD.gn
new file mode 100644
index 0000000..9eed4a2
--- /dev/null
+++ b/pw_presubmit/BUILD.gn
@@ -0,0 +1,21 @@
+# Copyright 2019 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+import("$dir_pw_docgen/docs.gni")
+
+pw_doc_group("docs") {
+ sources = [
+ "docs.rst",
+ ]
+}
diff --git a/pw_presubmit/README.md b/pw_presubmit/README.md
new file mode 100644
index 0000000..60bde53
--- /dev/null
+++ b/pw_presubmit/README.md
@@ -0,0 +1 @@
+# pw\_presubmit: Tools for running presubmit checks
diff --git a/pw_presubmit/docs.rst b/pw_presubmit/docs.rst
new file mode 100644
index 0000000..01389b3
--- /dev/null
+++ b/pw_presubmit/docs.rst
@@ -0,0 +1,83 @@
+.. _chapter-pw-presubmit:
+
+.. default-domain:: cpp
+
+.. highlight:: sh
+
+------------
+pw_presubmit
+------------
+The presubmit module provides Python tools for running presubmit checks and
+checking and fixing code format. It also includes the presubmit check script for
+the Pigweed repository, ``pigweed_presubmit.py``.
+
+Compatibility
+=============
+Python 3
+
+pw_presubmit Python package
+===========================
+
+Presubmit tools
+---------------
+A presubmit check is defined as a function or other callable. The function may
+take either no arguments or a list of the paths on which to run. Presubmit
+checks communicate failure by raising any exception.
+
+For example, either of these functions may be used as presubmit checks:
+
+.. code-block:: python
+
+ @pw_presubmit.filter_paths(endswith='.py')
+ def file_contains_ni(paths):
+ for path in paths:
+ with open(path) as file:
+ contents = file.read()
+ if 'ni' not in contents and 'nee' not in contents:
+ raise PresumitFailure('Files must say "ni"!', path=path)
+
+ def run_the_build():
+ subprocess.run(['make', 'release'], check=True)
+
+Presubmit checks are provided to the ``parse_args_and_run_presubmit`` or
+``run_presubmit`` function as a list. For example,
+
+.. code-block:: python
+
+ PRESUBMIT_CHECKS = [file_contains_ni, run_the_build]
+ sys.exit(0 if parse_args_and_run_presubmit(PRESUBMIT_CHECKS) else 1)
+
+Presubmit checks that accept a list of paths may use the ``filter_paths``
+decorator to automatically filter the paths list for file types they care about.
+
+Members
+^^^^^^^
+.. autofunction:: pw_presubmit.run_presubmit
+
+.. autofunction:: pw_presubmit.parse_args_and_run_presubmit
+
+.. autodecorator:: pw_presubmit.filter_paths
+
+.. autofunction:: pw_presubmit.call
+
+.. autoexception:: pw_presubmit.PresubmitFailure
+
+Presubmit checks
+----------------
+The pw_presubmit package includes presubmit checks that can be used with any
+project. These checks include:
+
+* Check code format of several languages including C, C++, and Python
+* Initialize a Python environment
+* Run all Python tests
+* Run pylint
+* Ensure source files are included in the GN and Bazel builds
+* Build and run all tests with GN
+* Build and run all tests with Bazel
+* Ensure all header files contain ``#pragma once``
+
+pw_presubmit.format_code
+------------------------
+The ``format_code`` submodule formats supported source files using external code
+format tools. The file ``format_code.py`` can be invoked directly from the
+command line or from ``pw`` as ``pw format``.
diff --git a/pw_presubmit/py/pw_presubmit/tools.py b/pw_presubmit/py/pw_presubmit/tools.py
index 0e1233b..d3ab723 100644
--- a/pw_presubmit/py/pw_presubmit/tools.py
+++ b/pw_presubmit/py/pw_presubmit/tools.py
@@ -13,18 +13,19 @@
# the License.
"""Tools for running presubmit checks in a Git repository.
-A presubmit checks are defined as a function or other callable. The function may
+Presubmit checks are defined as a function or other callable. The function may
take either no arguments or a list of the paths on which to run. Presubmit
checks communicate failure by raising any exception.
For example, either of these functions may be used as presubmit checks:
+ @pw_presubmit.filter_paths(endswith='.py')
def file_contains_ni(paths):
for path in paths:
with open(path) as file:
- contents = file.read()
- if 'ni' not in contents and 'nee' not in contents:
- raise PresumitFailure('Files must say "ni"!', path=path)
+ contents = file.read()
+ if 'ni' not in contents and 'nee' not in contents:
+ raise PresumitFailure('Files must say "ni"!', path=path)
def run_the_build():
subprocess.run(['make', 'release'], check=True)
@@ -543,7 +544,7 @@
@filter_paths(endswith='.h')
def pragma_once(paths: Iterable[str]) -> None:
- """Checks that all header files contain '#pragma once'."""
+ """Presubmit check that ensures all header files contain '#pragma once'."""
for path in paths:
with open(path) as file:
diff --git a/pw_span/BUILD.gn b/pw_span/BUILD.gn
index e28e253..52296d9 100644
--- a/pw_span/BUILD.gn
+++ b/pw_span/BUILD.gn
@@ -12,6 +12,7 @@
# License for the specific language governing permissions and limitations under
# the License.
+import("$dir_pw_docgen/docs.gni")
import("$dir_pw_unit_test/test.gni")
config("default_config") {
@@ -41,3 +42,9 @@
"span_test.cc",
]
}
+
+pw_doc_group("docs") {
+ sources = [
+ "docs.rst",
+ ]
+}
diff --git a/pw_span/README.md b/pw_span/README.md
new file mode 100644
index 0000000..23f2c5a
--- /dev/null
+++ b/pw_span/README.md
@@ -0,0 +1 @@
+# pw\_span: Stand-in for C++20's std::span
diff --git a/pw_span/docs.rst b/pw_span/docs.rst
new file mode 100644
index 0000000..5074958
--- /dev/null
+++ b/pw_span/docs.rst
@@ -0,0 +1,62 @@
+.. _chapter-pw-span:
+
+.. default-domain:: cpp
+
+.. highlight:: sh
+
+-------
+pw_span
+-------
+The pw_span module provides an implementation of C++20's
+`std::span <https://en.cppreference.com/w/cpp/container/span>`_, which is a
+non-owning view of an array of values. The intent is for ``pw::span``'s
+interface to exactly match ``std::span``.
+
+``pw::span`` is a convenient abstraction that wraps a pointer and a size.
+``pw::span`` is especially useful in APIs. Spans support implicit conversions
+from C arrays, ``std::array``, or any STL-style constainer, such as
+``std::string_view``.
+
+Functions operating on an array of bytes typically accept pointer and size
+arguments:
+
+.. code-block:: cpp
+
+ bool ProcessBuffer(char* buffer, size_t buffer_size);
+
+ bool DoStuff() {
+ ProcessBuffer(c_array, sizeof(c_array));
+ ProcessBuffer(array_object.data(), array_object.size());
+ ProcessBuffer(data_pointer, data_size);
+ }
+
+Pointer and size arguments can be replaced with a ``pw::span``:
+
+.. code-block:: cpp
+
+ // With pw::span, the buffer is passed as a single argument.
+ bool ProcessBuffer(const pw::span<uint8_t>& buffer);
+
+ bool DoStuff() {
+ ProcessBuffer(c_array);
+ ProcessBuffer(array_object);
+ ProcessBuffer(span(data_pointer, data_size));
+ }
+
+.. tip::
+ Use ``pw::span<std::byte>`` or ``pw::span<const std::bytes>`` to represent
+ spans of binary data. The ``pw::as_bytes`` or ``pw::as_writeable_bytes``
+ functions make converting to byte arrays very simple.
+
+ .. code-block:: cpp
+
+ void ProcessData(pw::span<const std::byte> data);
+
+ void DoStuff() {
+ std::array<AnyType, 7> data = { ... };
+ ProcessData(pw::as_bytes(data));
+ }
+
+Compatibility
+=============
+C++17
diff --git a/pw_status/BUILD.gn b/pw_status/BUILD.gn
index 6757fd8..c4e8a98 100644
--- a/pw_status/BUILD.gn
+++ b/pw_status/BUILD.gn
@@ -12,6 +12,7 @@
# License for the specific language governing permissions and limitations under
# the License.
+import("$dir_pw_docgen/docs.gni")
import("$dir_pw_unit_test/test.gni")
config("default_config") {
@@ -54,3 +55,9 @@
"status_with_size_test.cc",
]
}
+
+pw_doc_group("docs") {
+ sources = [
+ "docs.rst",
+ ]
+}
diff --git a/pw_status/README.md b/pw_status/README.md
index 2f3c97a..88b8646 100644
--- a/pw_status/README.md
+++ b/pw_status/README.md
@@ -1 +1 @@
-# pw\_status: Pigweed error codes
+# pw\_status: Pigweed status codes
diff --git a/pw_status/docs.rst b/pw_status/docs.rst
new file mode 100644
index 0000000..faee13b
--- /dev/null
+++ b/pw_status/docs.rst
@@ -0,0 +1,21 @@
+.. _chapter-pw-status:
+
+.. default-domain:: cpp
+
+.. highlight:: sh
+
+---------
+pw_status
+---------
+``pw::Status`` (``pw_status/status.h``) is a simple, zero-overhead status
+object. It uses Google's standard status codes, which are also used by projects
+such as `gRPC <https://github.com/grpc/grpc/blob/master/doc/statuscodes.md>`_.
+
+``pw::StatusWithSize`` (``pw_status/status_with_size.h``) is a convenient,
+efficent class for reporting a status along with an unsigned integer value.
+
+The classes in pw_status are used extensively by other Pigweed modules.
+
+Compatibility
+=============
+C++11
diff --git a/pw_string/README.md b/pw_string/README.md
new file mode 100644
index 0000000..2cfee8e
--- /dev/null
+++ b/pw_string/README.md
@@ -0,0 +1 @@
+# pw\_string: Utilities for building strings
diff --git a/pw_string/docs.rst b/pw_string/docs.rst
index 4c78276..a47b08f 100644
--- a/pw_string/docs.rst
+++ b/pw_string/docs.rst
@@ -1,4 +1,4 @@
-.. _chapter-string:
+.. _chapter-pw-string:
.. default-domain:: cpp
@@ -7,14 +7,16 @@
---------
pw_string
---------
-The string module provides utilities for working with strings.
+The string module provides efficient utilities for safely working with strings.
+The pw_string functions and classes always null-terminate strings and never
+overrun buffers. They do not allocate their own memory.
-Requirements
+Compatibility
=============
C++17
-Module Dependencies
--------------------
+Dependencies
+============
* pw_preprocessor
* pw_status
* pw_span
@@ -39,8 +41,8 @@
pw::StringBuilder
-----------------
StringBuilder facilitates building formatted strings in a fixed-size buffer.
-StringBuilder is safe, flexible, and results in much smaller code size than
-using std::ostringstream. However, applications sensitive to code size should
+It is designed to give the flexibility of std::string and std::ostringstream,
+but with a small footprint. However, applications sensitive to code size should
use StringBuilder with care.
Size report: replacing snprintf with pw::StringBuilder
