diff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp
index 616838fed702fec7..991674b34286ab16 100644
--- a/src/libcamera/pipeline_handler.cpp
+++ b/src/libcamera/pipeline_handler.cpp
@@ -136,6 +136,15 @@ PipelineHandler::~PipelineHandler()
  * is the Camera class which will receive configuration to apply from the
  * application.
  *
+ * Each pipeline handler implementation is responsible to validate that the
+ * configuration requested in \a config is exactly the same that is actually
+ * programmed and accepted by the hardware itself. If the format programmed
+ * differers from the one requested the pipeline handler shall return the
+ * error -EINVAL. If one streams configuration can't be satisfied by the
+ * hardware the pipeline handler does not need to try and program any other
+ * streams in \a config and the whole operation shall be consider to have
+ * failed.
+ *
  * \return 0 on success or a negative error code on error.
  */