doc: add example docs (automatically copied from component example re…

…admes) into online docs (#285)

components/bm8563/include/bm8563.hpp

@@ -69,6 +69,7 @@ class Bm8563 : public BasePeripheral<> {
   static uint8_t byte2bcd(uint8_t value) { return ((value / 10) << 4) + value % 10; }
 
   /// @brief Get the date and time.
+  /// @param ec The error code.
   /// @return The date and time.
   DateTime get_date_time(std::error_code &ec) {
     DateTime dt;
@@ -83,6 +84,7 @@ class Bm8563 : public BasePeripheral<> {
 
   /// @brief Set the date and time.
   /// @param dt The date and time.
+  /// @param ec The error code.
   void set_date_time(const DateTime &dt, std::error_code &ec) {
     set_date(dt.date, ec);
     if (ec)
@@ -91,6 +93,7 @@ class Bm8563 : public BasePeripheral<> {
   }
 
   /// @brief Get the date.
+  /// @param ec The error code.
   /// @return The date.
   Date get_date(std::error_code &ec) {
     logger_.info("getting date");
@@ -110,6 +113,7 @@ class Bm8563 : public BasePeripheral<> {
 
   /// @brief Set the date.
   /// @param d The date.
+  /// @param ec The error code.
   void set_date(const Date &d, std::error_code &ec) {
     logger_.info("setting date");
     const uint8_t data[] = {byte2bcd(d.day), byte2bcd(d.weekday),
@@ -119,6 +123,7 @@ class Bm8563 : public BasePeripheral<> {
   }
 
   /// @brief Get the time.
+  /// @param ec The error code.
   /// @return The time.
   Time get_time(std::error_code &ec) {
     logger_.info("getting time");
@@ -136,6 +141,7 @@ class Bm8563 : public BasePeripheral<> {
 
   /// @brief Set the time.
   /// @param t The time.
+  /// @param ec The error code.
   void set_time(const Time &t, std::error_code &ec) {
     logger_.info("Setting time");
     const uint8_t data[] = {byte2bcd(t.second), byte2bcd(t.minute), byte2bcd(t.hour)};
@@ -174,17 +180,28 @@ class Bm8563 : public BasePeripheral<> {
 };
 } // namespace espp
 
+/// @brief Compare two Date objects.
+/// @param lhs The left hand side.
+/// @param rhs The right hand side.
+/// @return True if the objects are equal.
 [[maybe_unused]] static bool operator==(const espp::Bm8563::Date &lhs,
                                         const espp::Bm8563::Date &rhs) {
   return lhs.year == rhs.year && lhs.month == rhs.month && lhs.weekday == rhs.weekday &&
          lhs.day == rhs.day;
 }
 
+/// @brief Compare two Time objects.
+/// @param lhs The left hand side.
+/// @param rhs The right hand side.
 [[maybe_unused]] static bool operator==(const espp::Bm8563::Time &lhs,
                                         const espp::Bm8563::Time &rhs) {
   return lhs.hour == rhs.hour && lhs.minute == rhs.minute && lhs.second == rhs.second;
 }
 
+/// @brief Compare two DateTime objects.
+/// @param lhs The left hand side.
+/// @param rhs The right hand side.
+/// @return True if the objects are equal.
 [[maybe_unused]] static bool operator==(const espp::Bm8563::DateTime &lhs,
                                         const espp::Bm8563::DateTime &rhs) {
   return lhs.date == rhs.date && lhs.time == rhs.time;

components/gfps_service/include/gfps_characteristic_callbacks.hpp

@@ -41,7 +41,8 @@ class GfpsCharacteristicCallback {
   /// Called when a Google Fast Pair Service characteristic is written
   /// \param conn_info The connection information for the device
   /// \param characteristic The characteristic to write
-  ///
+  /// \param value The value to write
+  /// \param length The length of the value
   void on_gfps_write(NimBLEConnInfo &conn_info, nearby_fp_Characteristic characteristic,
                      const uint8_t *value, size_t length) {
     auto gfps_ble_interface = gfps::get_ble_interface();

components/nvs/example/README.md

@@ -1,4 +1,4 @@
-# Serialization Example
+# NVS Example
 
 This example shows the use of the `NVS` component to save a variable to the NVS and load 
 it after reset. 

components/qwiicnes/include/qwiicnes.hpp

@@ -175,6 +175,11 @@ class QwiicNes : public BasePeripheral<> {
 };
 } // namespace espp
 
+/// @brief Overload the equality operator for the espp::QwiicNes::ButtonState
+///        struct.
+/// @param lhs The left hand side of the operator.
+/// @param rhs The right hand side of the operator.
+/// @return true if the two ButtonState structs are equal.
 static bool operator==(const espp::QwiicNes::ButtonState &lhs,
                        const espp::QwiicNes::ButtonState &rhs) {
   return lhs.raw == rhs.raw;

components/state_machine/include/deep_history_state.hpp

@@ -11,8 +11,16 @@ namespace espp::state_machine {
  */
 class DeepHistoryState : public StateBase {
 public:
+  /**
+   * @brief Construct a new Deep History State object
+   */
   DeepHistoryState()
       : StateBase() {}
+
+  /**
+   * @brief Construct a new Deep History State object
+   * @param _parent The parent state of this state
+   */
   explicit DeepHistoryState(StateBase *_parent)
       : StateBase(_parent) {}
 

components/state_machine/include/shallow_history_state.hpp

@@ -11,8 +11,16 @@ namespace espp::state_machine {
  */
 class ShallowHistoryState : public StateBase {
 public:
+  /**
+   * @brief Default constructor
+   */
   ShallowHistoryState()
       : StateBase() {}
+
+  /**
+   * @brief Constructor
+   * @param _parent The parent state
+   */
   explicit ShallowHistoryState(StateBase *_parent)
       : StateBase(_parent) {}
 

components/state_machine/include/state_base.hpp

@@ -6,7 +6,9 @@ namespace espp::state_machine {
 // Base Class for Events, abstract so you never instantiate.
 class EventBase {
 public:
+  /// Default constructor
   virtual ~EventBase() {}
+  /// Returns a string representation of the event
   virtual std::string to_string() const = 0;
 }; // class EventBase
 
@@ -26,12 +28,24 @@ class EventBase {
  */
 class StateBase {
 public:
+  /**
+   * @brief Default constructor
+   */
   StateBase()
       : _activeState(this)
       , _parentState(nullptr) {}
+
+  /**
+   * @brief Constructor that sets the parent state.
+   * @param[in] parent Pointer to parent state
+   */
   explicit StateBase(StateBase *parent)
       : _activeState(this)
       , _parentState(parent) {}
+
+  /**
+   * @brief Destructor
+   */
   virtual ~StateBase(void) {}
 
   /**
@@ -54,9 +68,7 @@ class StateBase {
 
   /**
    * @brief Calls handleEvent on the activeLeaf.
-   *
-   * @param[in] EventBase* Event needing to be handled
-   *
+   * @param[in] event Event needing to be handled
    * @return true if event is consumed, false otherwise
    */
   virtual bool handleEvent(EventBase *event) { return false; }
@@ -79,8 +91,7 @@ class StateBase {
    *  derived classes to immediately return the correct initial
    *  state pointer for quickly transitioning to the proper state
    *  during external transition handling.
-   *
-   * @return StateBase*  Pointer to initial substate
+   * @return Pointer to initial substate
    */
   virtual StateBase *getInitial(void) { return this; };
 
@@ -98,16 +109,14 @@ class StateBase {
   /**
    * @brief Will return _activeState if it exists, otherwise will
    *  return nullptr.
-   *
-   * @return StateBase*  Pointer to last active substate
+   * @return Pointer to last active substate
    */
   StateBase *getActiveChild(void) { return _activeState; }
 
   /**
    * @brief Will return the active leaf state, otherwise will return
    *  nullptr.
-   *
-   * @return StateBase*  Pointer to last active leaf state.
+   * @return Pointer to last active leaf state.
    */
   StateBase *getActiveLeaf(void) {
     if (_activeState != nullptr && _activeState != this)
@@ -119,8 +128,7 @@ class StateBase {
   /**
    * @brief Make this state the active substate of its parent and
    *  then recurse up through the tree to the root.
-   *
-   *  *Should only be called on leaf nodes!*
+   * @note Should only be called on leaf nodes!
    */
   virtual void makeActive(void) {
     if (_parentState != nullptr) {
@@ -162,6 +170,7 @@ class StateBase {
 
   /**
    * @brief Will set the parent state.
+   * @param[in] parent Pointer to parent state
    */
   void setParentState(StateBase *parent) { _parentState = parent; }
 

doc/conf_common.py

@@ -4,6 +4,7 @@
                # Needed as a trigger for running doxygen
                'esp_docs.esp_extensions.dummy_build_system',
                'esp_docs.esp_extensions.run_doxygen',
+               'myst_parser'
                ]
 
 exclude_paterns = ['build', '_build']

doc/en/adc/adc_example.md

@@ -0,0 +1,2 @@
+```{include} ../../../components/adc/example/README.md
+```

doc/en/adc/ads1x15.rst

@@ -4,6 +4,12 @@ ADS1x15 I2C ADC
 The `ADS1x15` provides a class for communicating with the ADS1x15 (ADS1015 and
 ADS1115) family of I2C ADC chips with configurable gain and sampling rate.
 
+.. ------------------------------- Example -------------------------------------
+
+.. toctree::
+
+   ads1x15_example
+
 .. ---------------------------- API Reference ----------------------------------
 
 API Reference

doc/en/adc/ads1x15_example.md

@@ -0,0 +1,2 @@
+```{include} ../../../components/ads1x15/example/README.md
+```

doc/en/adc/ads7138.rst

@@ -9,6 +9,12 @@ or digital outputs. It has an operating mode that allows the user to configure
 the device for a single conversion, or to automatically convert on a
 continuous basis.
 
+.. ------------------------------- Example -------------------------------------
+
+.. toctree::
+
+   ads7138_example
+
 .. ---------------------------- API Reference ----------------------------------
 
 API Reference

doc/en/adc/ads7138_example.md

@@ -0,0 +1,2 @@
+```{include} ../../../components/ads7138/example/README.md
+```

doc/en/adc/continuous_adc.rst

@@ -9,6 +9,12 @@ retrieves the data and filters it. When the user calls `get_mv(adc_channel_t)`,
 it simply returns the most recent filtered value for that channel, if it was
 configured.
 
+.. ------------------------------- Example -------------------------------------
+
+.. toctree::
+
+   adc_example
+
 .. ---------------------------- API Reference ----------------------------------
 
 API Reference

doc/en/adc/oneshot_adc.rst

@@ -8,6 +8,12 @@ any filtering on the data. Each time the user calls `read_raw(adc_channel_t)` or
 `read_mv(adc_channel_t)`, it block and trigger an analog read for the associated
 channel (if it was configured to do so).
 
+.. ------------------------------- Example -------------------------------------
+
+.. toctree::
+
+   adc_example
+
 .. ---------------------------- API Reference ----------------------------------
 
 API Reference

doc/en/adc/tla2528.rst

@@ -9,6 +9,12 @@ or digital outputs. It has an operating mode that allows the user to configure
 the device for a single conversion, or to automatically convert on a
 sequenced basis.
 
+.. ------------------------------- Example -------------------------------------
+
+.. toctree::
+
+   tla2528_example
+
 .. ---------------------------- API Reference ----------------------------------
 
 API Reference

doc/en/adc/tla2528_example.md

@@ -0,0 +1,2 @@
+```{include} ../../../components/tla2528/example/README.md
+```

doc/en/battery/max1704x.rst

@@ -24,6 +24,12 @@ voltage, and rate information is accessed using the I2C interface. The ICs are
 available in a tiny 0.9mm x 1.7mm, 8-bump wafer-level package (WLP), or a 2mm x
 2mm, 8-pin TDFN package.
 
+.. ------------------------------- Example -------------------------------------
+
+.. toctree::
+
+   max1704x_example
+
 .. ---------------------------- API Reference ----------------------------------
 
 API Reference

doc/en/battery/max1704x_example.md

@@ -0,0 +1,2 @@
+```{include} ../../../components/max1704x/example/README.md
+```

doc/en/bldc/bldc_motor.rst

@@ -19,6 +19,12 @@ The `BldcMotor` should be configured with a `BldcDriver` and optional `Sensor`
 (for angle & speed of the motor), and optional `CurrentSensor` (for measuring
 the phase currents of the motor and providing torque control).
 
+.. ------------------------------- Example -------------------------------------
+
+.. toctree::
+
+   bldc_motor_example
+
 .. ---------------------------- API Reference ----------------------------------
 
 API Reference

doc/en/bldc/bldc_motor_example.md

@@ -0,0 +1,2 @@
+```{include} ../../../components/bldc_motor/example/README.md
+```

doc/en/ble/ble_gatt_server.rst

@@ -5,6 +5,12 @@ The `BleGattServer` implements the standard BLE GATT server which has various
 APIs for controlling the server and adding services. It automatically builds and
 adds standard battery service and device information service.
 
+.. ------------------------------- Example -------------------------------------
+
+.. toctree::
+
+   ble_gatt_server_example
+
 .. ---------------------------- API Reference ----------------------------------
 
 API Reference

doc/en/ble/ble_gatt_server_example.md

@@ -0,0 +1,2 @@
+```{include} ../../../components/ble_gatt_server/example/README.md
+```

doc/en/ble/gfps_service.rst

@@ -7,6 +7,12 @@ also supports app matching / launching, as well as Google's `Find My Device`
 service. Finally, GFPS supports sharing device pairing info across that
 account's google devices and personalizing the name of the device.
 
+.. ------------------------------- Example -------------------------------------
+
+.. toctree::
+
+   gfps_service_example
+
 .. ---------------------------- API Reference ----------------------------------
 
 API Reference

doc/en/ble/gfps_service_example.md

@@ -0,0 +1,2 @@
+```{include} ../../../components/gfps_service/example/README.md
+```

doc/en/ble/hid_service.rst

@@ -5,6 +5,12 @@ The `HidService` implements the standard BLE HID service, providing dynamic and
 configurable HID input, output, and feature reports from a BLE peripheral to a
 BLE central.
 
+.. ------------------------------- Example -------------------------------------
+
+.. toctree::
+
+   hid_service_example
+
 .. ---------------------------- API Reference ----------------------------------
 
 API Reference

doc/en/ble/hid_service_example.md

@@ -0,0 +1,2 @@
+```{include} ../../../components/hid_service/example/README.md
+```