pw_bloat: Expand docs
This change fills in the how to use section in the bloat documentation.
Change-Id: Ib66c0bb8f47b35fd64f4c7cc87226f49a88e3f3c
diff --git a/pw_bloat/docs.rst b/pw_bloat/docs.rst
index 5767234..efc16b2 100644
--- a/pw_bloat/docs.rst
+++ b/pw_bloat/docs.rst
@@ -8,14 +8,68 @@
pw_bloat
--------
The bloat module provides tools to generate size report cards for output
-binaries.
+binaries using `Bloaty McBloatface <https://github.com/google/bloaty>`_ and
+Pigweed's GN build system.
+
+Bloat report cards allow tracking the memory usage of a system over time as code
+changes are made and provide a breakdown of which parts of the code have the
+largest size impact.
.. _bloat-howto:
Defining size reports
=====================
+Size reports are defined using the GN template ``pw_size_report``. The template
+requires at least two executable targets on which to perform a size diff. The
+base for the size diff can be specified either globally through the top-level
+``base`` argument, or individually per-binary within the ``binaries`` list.
-.. TODO(frolv): Explain how bloat works and how to set it up.
+**Arguments**
+
+* ``title``: Title for the report card.
+* ``base``: Optional default base target for all listed binaries.
+* ``binaries``: List of binaries to size diff. Each binary specifies a target,
+ a label for the diff, and optionally a base target that overrides the default
+ base.
+* ``source_filter``: Optional regex to filter labels in the diff output.
+* ``full_report``: Boolean flag indicating whether to output a full report of
+ all symbols in the binary, or a summary of the segment size changes. Default
+ false.
+
+.. code::
+
+ import("$dir_pw_bloat/bloat.gni")
+
+ executable("empty_base") {
+ sources = [ "empty_main.cc" ]
+ }
+
+ exectuable("hello_world_printf") {
+ sources = [ "hello_printf.cc" ]
+ }
+
+ exectuable("hello_world_iostream") {
+ sources = [ "hello_iostream.cc" ]
+ }
+
+ pw_size_report("my_size_report") {
+ title = "Hello world program using printf vs. iostream"
+ base = ":empty_base"
+ binaries = [
+ {
+ target = ":hello_world_printf"
+ label = "Hello world using printf"
+ },
+ {
+ target = ":hello_world_iostream"
+ label = "Hello world using iostream"
+ },
+ ]
+ }
+
+When the size report target runs, it will print its report card to stdout.
+Additionally, size report targets also generate ReST output, which is described
+below.
Documentation integration
=========================