Clarify event freeing in dispatch, post and publish APIs

Author: adel-mamin

libs/ao/ao.h

@@ -225,6 +225,9 @@ bool am_ao_publish_x_exclude(
  *
  * If the active object's event queue is full the function crashes with assert.
  *
+ * The library takes care of freeing the event once the
+ * active object handled the event.
+ *
  * The function is fast, thread safe and usable from
  * interrupt service routines (ISR).
  *
@@ -243,6 +246,9 @@ void am_ao_post_fifo(struct am_ao *ao, const struct am_event *event);
  *
  * Tries to free the event, if it was not posted.
  *
+ * The library takes care of freeing the event once the
+ * active object handled the event.
+ *
  * Statically allocated events (events for which am_event_is_static()
  * returns true) are never freed.
  *
@@ -265,6 +271,9 @@ bool am_ao_post_fifo_x(
  *
  * The event is then handled asynchronously by the active object.
  *
+ * The library takes care of freeing the event once the
+ * active object handled the event.
+ *
  * If active object's event queue is full the function crashes with assert.
  *
  * The function is fast, thread safe and usable from
@@ -285,6 +294,9 @@ void am_ao_post_lifo(struct am_ao *ao, const struct am_event *event);
  *
  * Tries to free the event, if it was not posted.
  *
+ * The library takes care of freeing the event once the
+ * active object handled the event.
+ *
  * Statically allocated events (events for which am_event_is_static()
  * returns true) are never freed.
  *

libs/hsm/hsm.h

@@ -283,6 +283,8 @@ struct am_hsm {
 /**
  * Synchronous dispatch of event to a given HSM.
  *
+ * Does not free the event - this is caller's responsibility.
+ *
  * @param hsm    the HSM handler
  * @param event  the event to dispatch
  */