docs: hardware: peripherals: add comparator docs

Add documentation for the comparator peripheral and shell.

Signed-off-by: Bjarki Arge Andreasen <[email protected]>

Author: bjarki-andreasen

doc/hardware/peripherals/comparator.rst

@@ -0,0 +1,69 @@
+.. _comparator_api:
+
+Comparator
+##########
+
+Overview
+********
+
+An analog comparator compares the voltages of two analog signals connected to its negative and
+positive inputs. If the voltage at the positive input is higher than the negative input, the
+comparator's output will be high, otherwise, it will be low.
+
+Comparators can typically set a trigger which triggers on output changes. This trigger can
+either invoke a callback, or its status can be polled.
+
+Related configuration options:
+
+* :kconfig:option:`CONFIG_COMPARATOR`
+
+Configuration
+*************
+
+Embedded comparators can typically be configured at runtime. When enabled, an initial
+configuration must be provided using the devicetree. At runtime, comparators can have their
+configuration updated using device driver specific APIs. The configuration will be applied
+when the comparator is resumed.
+
+Power management
+****************
+
+Comparators are enabled using power management. When resumed, the comparator will actively
+compare its inputs, producing an output and detecting edges. When suspended, the comparator
+will be inactive.
+
+Comparator shell
+****************
+
+The comparator shell provides the ``comp`` command with a set of subcommands for the
+:ref:`shell <shell_api>` module.
+
+The ``comp`` shell command provides the following subcommands:
+
+* ``get_output`` See :c:func:`comparator_get_output`
+* ``set_trigger`` See :c:func:`comparator_set_trigger`
+* ``await_trigger`` Awaits trigger using the following flow:
+  * Set trigger callback using :c:func:`comparator_set_trigger_callback`
+  * Await callback or time out after default or optionally provided timeout
+  * Clear trigger callback using :c:func:`comparator_set_trigger_callback`
+* ``trigger_is_pending`` See :c:func:`comparator_trigger_is_pending`
+
+Related configuration options:
+
+* :kconfig:option:`CONFIG_SHELL`
+* :kconfig:option:`CONFIG_COMPARATOR_SHELL`
+* :kconfig:option:`CONFIG_COMPARATOR_SHELL_AWAIT_TRIGGER_DEFAULT_TIMEOUT`
+* :kconfig:option:`CONFIG_COMPARATOR_SHELL_AWAIT_TRIGGER_MAX_TIMEOUT`
+
+.. note::
+   The power management shell can optionally be enabled alongside the comparator shell.
+
+   Related configuration options:
+
+   * :kconfig:option:`CONFIG_PM_DEVICE`
+   * :kconfig:option:`CONFIG_PM_DEVICE_SHELL`
+
+API Reference
+*************
+
+.. doxygengroup:: comparator_interface

doc/hardware/peripherals/index.rst

@@ -18,6 +18,7 @@ Peripherals
    clock_control.rst
    can/index.rst
    charger.rst
+   comparator.rst
    coredump.rst
    counter.rst
    dac.rst