daemon/session2: comment on event propagation

Minor, but I believe quite important. I stumbled across this while
writing the protocol layer article and thought it was not emphasized
enough in the docs.

diff --git a/daemon/session2.h b/daemon/session2.h
index 604c43a1d2944067163b75f414380a975319352c..514e7b7adaa9d608de67a7a60135421c2a6f0f70 100644 (file)
--- a/daemon/session2.h
+++ b/daemon/session2.h
@@ -575,7 +575,12 @@ enum protolayer_event_cb_result {
  *
  * When `PROTOLAYER_EVENT_PROPAGATE` is returned, iteration over the sequence
  * of layers continues. When `PROTOLAYER_EVENT_CONSUME` is returned, iteration
- * stops. */
+ * stops.
+ *
+ * **IMPORTANT:** A well-behaved layer will **ALWAYS** propagate events it knows
+ * nothing about. Only ever consume events you actually have good reason to
+ * consume (like TLS consumes `CONNECT` from TCP, because it needs to perform
+ * its own handshake first). */
 typedef enum protolayer_event_cb_result (*protolayer_event_cb)(
                enum protolayer_event_type event, void **baton,
                struct session2 *session, void *sess_data);