From db3f5878e1cf91a32e8028c07504c616fc006a4b Mon Sep 17 00:00:00 2001
From: Ricardo Rivera-Matos <rriveram@opensource.cirrus.com>
Date: Mon, 3 Apr 2023 11:10:44 -0500
Subject: [PATCH] charger: Adds basic stub API doc.

Adds a short stub doc as a placeholder for future documentation in the
charger API.

Signed-off-by: Ricardo Rivera-Matos <rriveram@opensource.cirrus.com>
---
 doc/develop/api/overview.rst         |  4 +++
 doc/hardware/peripherals/charger.rst | 38 ++++++++++++++++++++++++++++
 doc/hardware/peripherals/index.rst   |  1 +
 include/zephyr/drivers/charger.h     | 11 ++++++++
 4 files changed, 54 insertions(+)
 create mode 100644 doc/hardware/peripherals/charger.rst

diff --git a/doc/develop/api/overview.rst b/doc/develop/api/overview.rst
index d2bc12aef48c3df..70aa01c92ca1454 100644
--- a/doc/develop/api/overview.rst
+++ b/doc/develop/api/overview.rst
@@ -45,6 +45,10 @@ between major releases are available in the :ref:`zephyr_release_notes`.
      - Stable
      - 1.14
 
+   * - :ref:`charger_api`
+     - Experimental
+     - 3.3
+
    * - :ref:`counter_api`
      - Unstable
      - 1.14
diff --git a/doc/hardware/peripherals/charger.rst b/doc/hardware/peripherals/charger.rst
new file mode 100644
index 000000000000000..5b5dcf71e930c49
--- /dev/null
+++ b/doc/hardware/peripherals/charger.rst
@@ -0,0 +1,38 @@
+.. _charger_api:
+
+Chargers (Experimental API Stub Doc)
+#######################################
+
+The charger subsystem exposes an API to uniformly access battery charger devices. Currently,
+only reading data is supported.
+
+Note: This API is currently experimental and this doc will be significantly changed as new features
+are added to the API.
+
+Basic Operation
+***************
+
+Properties
+==========
+
+Fundamentally, a property is a configurable setting, state, or quantity that a charger device can
+measure.
+
+Chargers typically support multiple properties, such as temperature readings of the battery-pack
+or present-time current/voltage.
+
+Properties are fetched using a client allocated array of :c:struct:`charger_get_property`.  This
+array is then populated by values as according to its `property_type` field.
+
+Caching
+=======
+
+The Charger API explicitly provides no caching for its clients.
+
+
+.. _charger_api_reference:
+
+API Reference
+*************
+
+.. doxygengroup:: charger_interface
diff --git a/doc/hardware/peripherals/index.rst b/doc/hardware/peripherals/index.rst
index 5f67a85c0ce2c64..975f541f6f4e177 100644
--- a/doc/hardware/peripherals/index.rst
+++ b/doc/hardware/peripherals/index.rst
@@ -9,6 +9,7 @@ Peripherals
    adc.rst
    audio/index.rst
    canbus/index.rst
+   charger.rst
    coredump.rst
    counter.rst
    clock_control.rst
diff --git a/include/zephyr/drivers/charger.h b/include/zephyr/drivers/charger.h
index 59f516c96c6dbcb..0e092f7fd969041 100644
--- a/include/zephyr/drivers/charger.h
+++ b/include/zephyr/drivers/charger.h
@@ -7,6 +7,13 @@
 #ifndef ZEPHYR_INCLUDE_DRIVERS_CHARGER_H_
 #define ZEPHYR_INCLUDE_DRIVERS_CHARGER_H_
 
+/**
+ * @brief Charger Interface
+ * @defgroup charger_interface Charger Interface
+ * @ingroup io_interfaces
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */
@@ -121,6 +128,10 @@ static inline int z_impl_charger_get_prop(const struct device *dev,
 	return api->get_property(dev, props, props_len);
 }
 
+/**
+ * @}
+ */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */