MessageDict: Add a bit of docstring documentation.

zerver/lib/actions.py

@@ -1525,6 +1525,13 @@ def do_send_messages(messages_maybe_none: Sequence[Optional[MutableMapping[str,
         for message in messages:
             do_widget_post_save_actions(message)
 
+    # This next loop is responsible for notifying other parts of the
+    # Zulip system about the messages we just committed to the database:
+    # * Notifying clients via send_event
+    # * Triggering outgoing webhooks via the service event queue.
+    # * Updating the `first_message_id` field for streams without any message history.
+    # * Implementing the Welcome Bot reply hack
+    # * Adding links to the embed_links queue for open graph processing.
     for message in messages:
         realm_id: Optional[int] = None
         if message['message'].is_stream_message():

zerver/lib/message.py

@@ -171,6 +171,26 @@ def save_message_rendered_content(message: Message, content: str) -> str:
     return rendered_content
 
 class MessageDict:
+    """MessageDict is the core class responsible for marshalling Message
+    objects obtained from the database into a format that can be sent
+    to clients via the Zulip API, whether via `GET /messages`,
+    outgoing webhooks, or other code paths.  There are two core flows through
+    which this class is used:
+
+    * For just-sent messages, we construct a single `wide_dict` object
+      containing all the data for the message and the related
+      UserProfile models (sender_info and recipient_info); this object
+      can be stored in queues, caches, etc., and then later turned
+      into an API-format JSONable dictionary via finalize_payload.
+
+    * When fetching messages from the database, we fetch their data in
+      bulk using messages_for_ids, which makes use of caching, bulk
+      fetches that skip the Django ORM, etc., to provide an optimized
+      interface for fetching hundreds of thousands of messages from
+      the database and then turning them into API-format JSON
+      dictionaries.
+
+    """
     @staticmethod
     def wide_dict(message: Message, realm_id: Optional[int]=None) -> Dict[str, Any]:
         '''