diff --git a/include/event2/buffer.h b/include/event2/buffer.h
index 645a1908..3791e92d 100644
--- a/include/event2/buffer.h
+++ b/include/event2/buffer.h
@@ -589,10 +589,10 @@ struct evbuffer_file_segment *evbuffer_file_segment_new(
 void evbuffer_file_segment_free(struct evbuffer_file_segment *seg);
 
 /**
-   Add cleanup callback and argument for the callback to an 
-   evbuffer_file_segment. 
+   Add cleanup callback and argument for the callback to an
+   evbuffer_file_segment.
 
-   The cleanup callback will be invoked when no more references to the 
+   The cleanup callback will be invoked when no more references to the
    evbuffer_file_segment exist.
  **/
 void evbuffer_file_segment_add_cleanup_cb(struct evbuffer_file_segment *seg,
diff --git a/include/event2/event.h b/include/event2/event.h
index 17b80348..288ce39c 100644
--- a/include/event2/event.h
+++ b/include/event2/event.h
@@ -1347,9 +1347,13 @@ typedef int (*event_base_foreach_event_cb)(const struct event_base *, const stru
    Iterate over all added or active events events in an event loop, and invoke
    a given callback on each one.
 
-   The callback must not call any function that modifies the event base, or
-   modifies any event in the event base.  Doing so is unsupported and
-   will lead to undefined behavior.
+   The callback must not call any function that modifies the event base, that
+   modifies any event in the event base, or that adds or removes any event to
+   the event base.  Doing so is unsupported and will lead to undefined
+   behavior -- likely, to crashes.
+
+   event_base_foreach_event() holds a lock on the event_base() for the whole
+   time it's running: slow callbacks are not advisable.
 
    The callback function must return 0 to continue iteration, or some other
    integer to stop iterating.