docs: Tweak some documentation around send_event.

docs/subsystems/events-system.md

@@ -77,6 +77,11 @@ example, an event containing direct message content is sent to the
 entire organization. However, if an event isn't sent to enough clients,
 there will likely be user-visible real-time sync bugs.
 
+As indicated in the name, `send_event_on_commit` is intended to be
+called inside the database transaction that is changing the state
+itself; this design ensures that the event is only sent if the
+transaction successfully commits.
+
 Most of the hard work in event generation is about defining consistent
 event dictionaries that are clear, readable, will be useful to the
 wide range of possible clients, and make it easy for developers.

docs/tutorials/new-feature-tutorial.md

@@ -277,11 +277,13 @@ first contacts the server, the server sends the client its
 initial state. Subsequently, clients subscribe to "events," which can
 (among other things) indicate that settings have changed.
 
-For the backend piece, we will need our action to make a call to `send_event_on_commit`
+For the backend piece, we will need our action to make a call to
-to send the event to clients that are active. We will also need to
+`send_event_on_commit` to send the event to clients that are active
-modify `fetch_initial_state_data` so that the new field is passed to
+(The event is only sent after the current database transaction
-clients. See [our event system docs](../subsystems/events-system.md) for all the
+commits, hence the name). We will also need to modify
-gory details.
+`fetch_initial_state_data` so that the new field is passed to
+clients. See [our event system docs](../subsystems/events-system.md)
+for all the gory details.
 
 Anyway, getting back to implementation details...
 

docs/tutorials/writing-views.md

@@ -332,9 +332,9 @@ def update_realm(
 ```
 
 `realm.save()` actually saves the changes to the realm to the
-database, and `send_event_on_commit` sends the event to active clients belonging
+database, and `send_event_on_commit` sends the event to active clients
-to the provided list of users (in this case, all active users in the
+belonging to the provided list of users (in this case, all active
-Zulip realm).
+users in the Zulip realm), once the current transaction completes.
 
 ### Calling from the web application
 

zerver/lib/test_classes.py

@@ -2052,11 +2052,18 @@ class ZulipTestCase(ZulipTestCaseMixin, TestCase):
         # So explicitly change parameter name to 'notice' to work around this problem
         with (
             mock.patch("zerver.tornado.event_queue.process_notification", lst.append),
-            # Some `send_event_rollback_unsafe` calls need to be executed only after the
+            # Some `send_event_rollback_unsafe` calls need to be
-            # current transaction commits (using `on_commit` hooks). Because the transaction
+            # executed only after the current transaction commits
-            # in Django tests never commits (rather, gets rolled back after the test completes),
+            # (mainly those using the `send_event_on_commit` wrapper, which
-            # such events would never be sent in tests, and we would be unable to verify them.
+            # sends the actual event inside an `on_commit` hook).
-            # Hence, we use this helper to make sure the `send_event_rollback_unsafe` calls actually run.
+            #
+            # Because the outer transaction in Django tests never
+            # commits (it gets rolled back when the test completes
+            # to restore the database to the desired state for the
+            # next test), such events would never be sent in
+            # tests, and we would be unable to verify them.
+            # Hence, we use this helper to make sure the
+            # `send_event_rollback_unsafe` calls actually run.
             self.captureOnCommitCallbacks(execute=True),
         ):
             yield lst