pw_digital_io: Doxygenify DigitalIoOptional description

Change-Id: I80e021b9e68566b2c40255056e840a2722e40a76
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/152130
Reviewed-by: Anton Markov <amarkov@google.com>
Commit-Queue: Kayce Basques <kayce@google.com>
Reviewed-by: Kayce Basques <kayce@google.com>
Pigweed-Auto-Submit: Kayce Basques <kayce@google.com>
Reviewed-by: Anthony DiGirolamo <tonymd@google.com>

docs/BUILD.gn

@@ -135,6 +135,7 @@ _doxygen_input_files = [
   "$dir_pw_containers/public/pw_containers/inline_queue.h",
   "$dir_pw_chrono/public/pw_chrono/system_clock.h",
   "$dir_pw_chrono/public/pw_chrono/system_timer.h",
+  "$dir_pw_digital_io/public/pw_digital_io/digital_io.h",
   "$dir_pw_function/public/pw_function/scope_guard.h",
   "$dir_pw_hdlc/public/pw_hdlc/decoder.h",
   "$dir_pw_hdlc/public/pw_hdlc/encoder.h",

pw_digital_io/docs.rst

@@ -272,6 +272,14 @@ Backend Implemention Notes
 * Calling ``Enable()`` on a line that is already enabled should be a no-op. In
   particular, the state of an already-enabled output line should not change.
 
+-------------
+API reference
+-------------
+.. note::
+   This API reference is incomplete.
+
+.. doxygenclass:: pw::digital_io::DigitalIoOptional
+
 ------------
 Dependencies
 ------------

pw_digital_io/public/pw_digital_io/digital_io.h

@@ -42,29 +42,30 @@ enum class InterruptTrigger : int {
 // the line. It is backend-specific if, when, and how this state is updated.
 using InterruptHandler = ::pw::Function<void(State sampled_state)>;
 
-// A digital I/O line that may support input, output, and interrupts, but makes
-// no guarantees about whether any operations are supported. You must check the
-// various provides_* flags before calling optional methods. Unsupported methods
-// invoke PW_CRASH.
-//
-// All methods are potentially blocking. Unless otherwise specified, access from
-// multiple threads to a single line must be externally synchronized - for
-// example using pw::Borrowable. Unless otherwise specified, none of the methods
-// are safe to call from an interrupt handler. Therefore, this abstraction may
-// not be suitable for bitbanging and other low-level uses of GPIO.
-//
-// Note that the initial state of a line is not guaranteed to be consistent with
-// either the "enabled" or "disabled" state. Users of the API who need to ensure
-// the line is disabled (ex. output not driving the line) should call Disable.
-//
-// This class should almost never be used in APIs directly. Instead, use one of
-// the derived classes that explicitly supports the functionality that your
-// API needs.
-//
-// This class cannot be extended directly. Instead, extend one of the
-// derived classes that explicitly support the functionality that you want to
-// implement.
-//
+/// A digital I/O line that may support input, output, and interrupts, but makes
+/// no guarantees about whether any operations are supported. You must check the
+/// various `provides_*` flags before calling optional methods. Unsupported
+/// methods invoke `PW_CRASH`.
+///
+/// All methods are potentially blocking. Unless otherwise specified, access
+/// from multiple threads to a single line must be externally synchronized - for
+/// example using `pw::Borrowable`. Unless otherwise specified, none of the
+/// methods are safe to call from an interrupt handler. Therefore, this
+/// abstraction may not be suitable for bitbanging and other low-level uses of
+/// GPIO.
+///
+/// Note that the initial state of a line is not guaranteed to be consistent
+/// with either the "enabled" or "disabled" state. Users of the API who need to
+/// ensure the line is disabled (ex. output not driving the line) should call
+/// `Disable()`.
+///
+/// This class should almost never be used in APIs directly. Instead, use one of
+/// the derived classes that explicitly supports the functionality that your
+/// API needs.
+///
+/// This class cannot be extended directly. Instead, extend one of the
+/// derived classes that explicitly support the functionality that you want to
+/// implement.
 class DigitalIoOptional {
  public:
   virtual ~DigitalIoOptional() = default;