docs: module_structure docs wording improvements
Change-Id: I09d330200b9a9f491a992fe5d39522cf55bb39e3
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/22845
Reviewed-by: Armando Montanez <amontanez@google.com>
Commit-Queue: Wyatt Hepler <hepler@google.com>
diff --git a/docs/module_structure.rst b/docs/module_structure.rst
index c10106a..586fca0 100644
--- a/docs/module_structure.rst
+++ b/docs/module_structure.rst
@@ -197,8 +197,8 @@
Compile-time configuration provides flexibility, but also imposes
restrictions. A module can only have one configuration in a given build.
- Compile-time configuration also makes testing more difficult. Where
- appropriate, consider alternatives such as C++ templates or runtime
+ This makes testing modules with compile-time configuration more difficult.
+ Where appropriate, consider alternatives such as C++ templates or runtime
configuration.
Declaring configuration
@@ -249,6 +249,8 @@
pw_foo_CONFIG = pw_build_DEFAULT_MODULE_CONFIG
}
+ # An example source set for each potential config header location follows.
+
# Publicly accessible configuration header (most common)
pw_source_set("config") {
public = [ "public/pw_foo/config.h" ]
@@ -286,7 +288,7 @@
``-DPW_FOO_INPUT_BUFFER_SIZE_BYTES=256``, or in a header file included with the
``-include`` option.
-This example shows how two ways to configure a module in the GN build system.
+This example shows two ways to configure a module in the GN build system.
.. code-block::
@@ -332,18 +334,22 @@
build variable. Facades typically are bundled with a build system library that
depends on the backend.
-Modules should only use facades when necessary. Since they are fixed at compile
-time, runtime dependency injection is not possible. Where appropriate, modules
-should use other mechanisms, such as virtual interfaces or callbacks, in place
-of facades.
-
Facades are essential in some circumstances:
* Low-level, platform-specific features (:ref:`module-pw_cpu_exception`).
* Features that require a macro or non-virtual function interface
- (:ref:`module-pw_tokenizer`),
+ (:ref:`module-pw_log`, :ref:`module-pw_assert`).
* Highly leveraged code where a virtual interface or callback is too costly or
- cumbersome (:ref:`module-pw_log`, :ref:`module-pw_assert`).
+ cumbersome (:ref:`module-pw_tokenizer`).
+
+.. caution::
+
+ Modules should only use facades when necessary. Facades are permanently locked
+ to a particular implementation at compile time. Multpile backends cannot be
+ used in one build, and runtime dependency injection is not possible, which
+ makes testing difficult. Where appropriate, modules should use other
+ mechanisms, such as virtual interfaces, callbacks, or templates, in place of
+ facades.
The GN build system provides the
:ref:`pw_facade template<module-pw_build-facade>` as a convenient way to declare
@@ -407,7 +413,7 @@
6. Add folder alias for new module variable in ``/modules.gni``
- - dir_pw_new = "$dir_pigweed/pw_new"
+ - ``dir_pw_new = get_path_info("pw_new", "abspath")``
7. Add new module to main GN build
