pw_async2: Update docs

Change-Id: I0d798885861b5d002de7c415a7289a5873665abb
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/243999
Presubmit-Verified: CQ Bot Account <[email protected]>
Commit-Queue: Kayce Basques <[email protected]>
Lint: Lint 🤖 <[email protected]>
Reviewed-by: Taylor Cramer <[email protected]>

pw_async2/backends.rst

@@ -3,10 +3,21 @@
 ==================
 pw_async2 backends
 ==================
-.. TODO: b/323607687 - Add backend guidance here
+The :ref:`pw_async2 interface <module-pw_async2-reference>` must be fulfilled
+by a concrete implementation. You can use one of the Pigweed-provided backends
+listed below or roll your own. If you roll your own, please consider
+:ref:`contributing <docs-get-started-upstream>` it to upstream Pigweed!
+
+.. _epoll: https://man7.org/linux/man-pages/man7/epoll.7.html
+
+* :ref:`module-pw_async2_basic`. A backend that uses a thread-notification-based
+  :cpp:class:`pw::async2::Dispatcher`.
+* :ref:`module-pw_async2_epoll`. A backend that uses a :cpp:class:`pw::async2::Dispatcher`
+  backed by Linux's `epoll`_ notification system.
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    Basic <../pw_async2_basic/docs>
    Linux epoll <../pw_async2_epoll/docs>

pw_async2/docs.rst

@@ -13,7 +13,7 @@ pw_async2
    - **Pluggable**: Your existing event loop, work queue, or task scheduler
      can run the ``Dispatcher`` without any extra threads.
    - **Coroutine-capable**: C++20 coroutines work just like other tasks, and can
-     easily plug into an existing ``pw_async2`` systems.
+     easily plug into an existing ``pw_async2`` system.
 
 :cpp:class:`pw::async2::Task` is Pigweed's async primitive. ``Task`` objects
 are cooperatively-scheduled "threads" which yield to the
@@ -22,15 +22,15 @@ progress, the ``Dispatcher`` will run it again. For example:
 
 .. tab-set::
 
-   .. tab-item:: Manual ``Task`` State Machine
+   .. tab-item:: Manual task state machine
 
       .. literalinclude:: examples/basic.cc
          :language: cpp
          :linenos:
          :start-after: [pw_async2-examples-basic-manual]
          :end-before: [pw_async2-examples-basic-manual]
 
-   .. tab-item:: Coroutine Function
+   .. tab-item:: Coroutine function
 
       .. literalinclude:: examples/basic.cc
          :language: cpp
@@ -75,6 +75,24 @@ Tasks can then be run on a :cpp:class:`pw::async2::Dispatcher` using the
 
       And more.
 
+.. grid:: 2
+
+   .. grid-item-card:: :octicon:`code-square` Backends
+      :link: module-pw_async2-backends
+      :link-type: ref
+      :class-item: sales-pitch-cta-secondary
+
+      You can fulfill the ``pw_async2`` interface with a Pigweed-provided
+      backend or roll your own.
+
+   .. grid-item-card:: :octicon:`pencil` Pigweed blog: C++20 coroutines
+      :link: docs-blog-05-coroutines
+      :link-type: ref
+      :class-item: sales-pitch-cta-secondary
+
+      A blog post on how Pigweed implements coroutines without heap
+      allocation, and challenges encountered along the way.
+
 .. toctree::
    :hidden:
    :maxdepth: 1

pw_async2/guides.rst

@@ -14,8 +14,8 @@ Guides
 
 .. _module-pw_async2-guides-tasks:
 
-Dispatchers and tasks
-=====================
+How a dispatcher manages tasks
+==============================
 The purpose of a :cpp:class:`pw::async2::Dispatcher` is to keep track of a set
 of :cpp:class:`pw::async2::Task` objects and run them to completion. The
 dispatcher is essentially a scheduler for cooperatively-scheduled
@@ -37,8 +37,8 @@ dispatcher will then invoke ``DoPend`` once more, continuing the cycle until
 
 .. _module-pw_async2-guides-waking:
 
-Waking
-======
+Waking tasks
+============
 When a task is unable to complete without waiting, the implementor of
 ``DoPend`` must return ``Pending`` and should arrange for the task to be reawoken
 once ``DoPend`` may be able to make more progress. This is done by calling
@@ -107,7 +107,6 @@ C++20 users can define tasks using coroutines!
    :end-before: [pw_async2-examples-basic-coro]
 
 Any value with a ``Poll<T> Pend(Context&)`` method can be passed to
-
 ``co_await``, which will return with a ``T`` when the result is ready.
 
 To return from a coroutine, ``co_return <expression>`` must be used instead of
@@ -116,8 +115,8 @@ the usual ``return <expression>`` syntax. Because of this, the
 coroutines. :c:macro:`PW_CO_TRY` and :c:macro:`PW_CO_TRY_ASSIGN` should be
 used instead.
 
-For a more detailed explanation of Pigweed's coroutine support, see the
-documentation on the :cpp:class:`pw::async2::Coro` type.
+For a more detailed explanation of Pigweed's coroutine support, see
+:cpp:class:`pw::async2::Coro`.
 
 .. _module-pw_async2-guides-timing:
 
@@ -136,5 +135,5 @@ for a timeout or deadline using the
 Additionally, code which uses :cpp:class:`pw::async2::TimeProvider` for timing
 can be tested with simulated time using
 :cpp:class:`pw::async2::SimulatedTimeProvider`. Doing so helps avoid
-timing-dependent test flakes, as well as ensure that tests are fast since they
+timing-dependent test flakes and helps ensure that tests are fast since they
 don't need to wait for real-world time to elapse.

pw_async2_epoll/docs.rst

@@ -3,9 +3,7 @@
 ===================
 pw_async2_epoll
 ===================
+.. _epoll: https://man7.org/linux/man-pages/man7/epoll.7.html
 
---------
-Overview
---------
 This is a simple backend for ``pw_async2`` that uses a ``Dispatcher`` backed
-by Linux's epoll notification system.
+by Linux's `epoll`_ notification system.