docs: Begin Doxygenification of pw::i2c::Initiator
Change-Id: I024a476b75ba3d6c72a3849d2b69c3f00caf567a
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/146890
Reviewed-by: Chad Norvell <chadnorvell@google.com>
Reviewed-by: Kayce Basques <kayce@google.com>
Commit-Queue: Kayce Basques <kayce@google.com>
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index 6fa6eb5..598a731 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -136,6 +136,7 @@
"$dir_pw_hdlc/public/pw_hdlc/decoder.h",
"$dir_pw_hdlc/public/pw_hdlc/encoder.h",
"$dir_pw_interrupt/public/pw_interrupt/context.h",
+ "$dir_pw_i2c/public/pw_i2c/initiator.h",
"$dir_pw_log_tokenized/public/pw_log_tokenized/handler.h",
"$dir_pw_log_tokenized/public/pw_log_tokenized/metadata.h",
"$dir_pw_rpc/public/pw_rpc/internal/config.h",
diff --git a/pw_i2c/docs.rst b/pw_i2c/docs.rst
index 78110e0..4a96584 100644
--- a/pw_i2c/docs.rst
+++ b/pw_i2c/docs.rst
@@ -17,20 +17,11 @@
------------------
.. inclusive-language: disable
-The common interface for initiating transactions with devices on an I2C bus.
-Other documentation sources may call this style of interface an I2C "master",
-"central" or "controller".
+.. doxygenclass:: pw::i2c::Initiator
+ :members:
.. inclusive-language: enable
-.. note::
-
- ``Initiator`` uses internal synchronization, so it is safe to
- initiate transactions from multiple threads. However, write+read transactions
- may not be atomic with multiple controllers on the bus. Furthermore, devices
- may require specific sequences of transactions, and application logic must
- provide the synchronization to execute these sequences correctly.
-
pw::i2c::Device
---------------
The common interface for interfacing with generic I2C devices. This object
diff --git a/pw_i2c/public/pw_i2c/initiator.h b/pw_i2c/public/pw_i2c/initiator.h
index 8b09a67..7d9d6dd 100644
--- a/pw_i2c/public/pw_i2c/initiator.h
+++ b/pw_i2c/public/pw_i2c/initiator.h
@@ -22,18 +22,26 @@
namespace pw::i2c {
-// Base driver interface for I2C initiating I2C transactions in a thread safe
-// manner. Other documentation sources may call this style of interface an I2C
-// "master", "central" or "controller". // inclusive-language: ignore
-//
-// The Initiator is not required to support 10bit addressing. If only 7bit
-// addressing is supported, the Initiator will assert when given an address
-// which is out of 7bit address range.
-//
-// The implementer of this pure virtual interface is responsible for ensuring
-// thread safety and enabling functionality such as initialization,
-// configuration, enabling/disabling, unsticking SDA, and detecting device
-// address registration collisions.
+/// @brief The common, base driver interface for initiating thread-safe
+/// transactions with devices on an I2C bus. Other documentation may call this
+/// style of interface an I2C "master", <!-- inclusive-language: disable -->
+/// "central", or "controller".
+///
+/// `Initiator` isn't required to support 10-bit addressing. If only 7-bit
+/// addressing is supported, `Initiator` asserts when given an address
+/// that is out of 7-bit address range.
+///
+/// The implementer of this pure virtual interface is responsible for ensuring
+/// thread safety and enabling functionality such as initialization,
+/// configuration, enabling/disabling, unsticking SDA, and detecting device
+/// address registration collisions.
+///
+/// @note `Initiator` uses internal synchronization, so it's safe to
+/// initiate transactions from multiple threads. However, write+read
+/// transactions may not be atomic with multiple controllers on the bus.
+/// Furthermore, devices may require specific sequences of transactions, and
+/// application logic must provide the synchronization to execute these
+/// sequences correctly.
class Initiator {
public:
virtual ~Initiator() = default;
