diff --git a/src/audio/component.c b/src/audio/component.c
index 17edc7fb4678..2f18740f8d0e 100644
--- a/src/audio/component.c
+++ b/src/audio/component.c
@@ -110,6 +110,10 @@ void comp_unregister(struct comp_driver_info *drv)
 	irq_local_enable(flags);
 }
 
+/* NOTE: Keep the component state diagram up to date:
+ * sof-docs/developer_guides/firmware/components/images/comp-dev-states.pu
+ */
+
 int comp_set_state(struct comp_dev *dev, int cmd)
 {
 	int requested_state = comp_get_requested_state(cmd);
diff --git a/src/include/sof/audio/component.h b/src/include/sof/audio/component.h
index a52d344a28cf..a4f5b9091b3b 100644
--- a/src/include/sof/audio/component.h
+++ b/src/include/sof/audio/component.h
@@ -51,47 +51,16 @@ struct dai_hw_params;
  *  @{
  */
 
-/** \name Audio Component States
- *  @{
+/* NOTE: Keep the component state diagram up to date:
+ * sof-docs/developer_guides/firmware/components/images/comp-dev-states.pu
  */
 
-/**
- * States may transform as below:-
- * \verbatim
- *                                  +---------------------------------------+
- *                                  |                                       |
- *                            -------------                                 |
- *                   pause    |           |    stop                         |
- *              +-------------| ACTIVITY  |---------------+                 |
- *              |             |           |               |      prepare    |
- *              |             -------------               |   +---------+   |
- *              |                ^     ^                  |   |         |   |
- *              |                |     |                  |   |         |   |
- *              v                |     |                  v   |         |   |
- *       -------------           |     |             -------------      |   |
- *       |           |   release |     |   start     |           |      |   |
- *       |   PAUSED  |-----------+     +-------------|  PREPARE  |<-----+   |
- *       |           |                               |           |          |
- *       -------------                               -------------          |
- *              |                                      ^     ^              |
- *              |               stop                   |     |              |
- *              +--------------------------------------+     |              |
- *                                                           | prepare      |
- *                            -------------                  |              |
- *                            |           |                  |              |
- *                ----------->|   READY   |------------------+              |
- *                    reset   |           |                                 |
- *                            -------------                                 |
- *                                  ^                                       |
- *                                  |                 xrun                  |
- *                                  +---------------------------------------+
- *
- * \endverbatim
+/** \name Audio Component States
+ *  @{
  */
-
 #define COMP_STATE_INIT		0	/**< Component being initialised */
-#define COMP_STATE_READY	1       /**< Component inactive, but ready */
-#define COMP_STATE_SUSPEND	2       /**< Component suspended */
+#define COMP_STATE_READY	1	/**< Component inactive, but ready */
+#define COMP_STATE_SUSPEND	2	/**< Component suspended */
 #define COMP_STATE_PREPARE	3	/**< Component prepared */
 #define COMP_STATE_PAUSED	4	/**< Component paused */
 #define COMP_STATE_ACTIVE	5	/**< Component active */
@@ -551,6 +520,19 @@ static inline void comp_shared_commit(struct comp_dev *dev)
  * @param dev Component device.
  * @param cmd Command, one of <i>COMP_TRIGGER_...</i>.
  * @return 0 if succeeded, error code otherwise.
+ *
+ * This function should be called by a component implementation at the beginning
+ * of its state transition to verify whether the trigger is valid in the
+ * current state and abort the transition otherwise.
+ *
+ * Typically the COMP_STATE_READY as the initial state is set directly
+ * by the component's implementation of _new().
+ *
+ * COMP_TRIGGER_PREPARE is called from the component's prepare().
+ *
+ * COMP_TRIGGER_START/STOP is called from trigger().
+ *
+ * COMP_TRIGGER_RESET is called from reset().
  */
 int comp_set_state(struct comp_dev *dev, int cmd);