Improve deprecated markers

deltachat-jsonrpc/src/api.rs

@@ -678,7 +678,7 @@ impl CommandApi {
         ChatId::new(chat_id).get_fresh_msg_cnt(&ctx).await
     }
 
-    /// Gets messages to be processed by the bot and returns their IDs.
+    /// (deprecated) Gets messages to be processed by the bot and returns their IDs.
     ///
     /// Only messages with database ID higher than `last_msg_id` config value
     /// are returned. After processing the messages, the bot should
@@ -686,7 +686,7 @@ impl CommandApi {
     /// or manually updating the value to avoid getting already
     /// processed messages.
     ///
-    /// DEPRECATED 2026-04: This returns the message's id as soon as the first part arrives,
+    /// Deprecated 2026-04: This returns the message's id as soon as the first part arrives,
     /// even if it is not fully downloaded yet.
     /// The bot needs to wait for the message to be fully downloaded.
     /// Since this is usually not the desired behavior,
@@ -705,7 +705,7 @@ impl CommandApi {
         Ok(msg_ids)
     }
 
-    /// Waits for messages to be processed by the bot and returns their IDs.
+    /// (deprecated) Waits for messages to be processed by the bot and returns their IDs.
     ///
     /// This function is similar to [`get_next_msgs`],
     /// but waits for internal new message notification before returning.
@@ -716,6 +716,13 @@ impl CommandApi {
     /// To shutdown the bot, stopping I/O can be used to interrupt
     /// pending or next `wait_next_msgs` call.
     ///
+    /// Deprecated 2026-04: This returns the message's id as soon as the first part arrives,
+    /// even if it is not fully downloaded yet.
+    /// The bot needs to wait for the message to be fully downloaded.
+    /// Since this is usually not the desired behavior,
+    /// bots should instead use the #DC_EVENT_INCOMING_MSG / [`types::events::EventType::IncomingMsg`]
+    /// event for getting notified about new messages.
+    ///
     /// [`get_next_msgs`]: Self::get_next_msgs
     async fn wait_next_msgs(&self, account_id: u32) -> Result<Vec<u32>> {
         let ctx = self.get_context(account_id).await?;

deltachat-rpc-client/src/deltachat_rpc_client/account.py

@@ -405,7 +405,15 @@ class Account:
 
     @futuremethod
     def wait_next_messages(self) -> list[Message]:
-        """Wait for new messages and return a list of them."""
+        """(deprecated) Wait for new messages and return a list of them. Meant for bots.
+
+        Deprecated 2026-04: This returns the message's id as soon as the first part arrives,
+        even if it is not fully downloaded yet.
+        The bot needs to wait for the message to be fully downloaded.
+        Since this is usually not the desired behavior,
+        bots should instead use the `EventType.INCOMING_MSG`
+        event for getting notified about new messages.
+        """
         next_msg_ids = yield self._rpc.wait_next_msgs.future(self.id)
         return [Message(self, msg_id) for msg_id in next_msg_ids]
 

src/context.rs

@@ -1142,12 +1142,12 @@ ORDER BY m.timestamp DESC,m.id DESC",
         Ok(list)
     }
 
-    /// Returns a list of messages with database ID higher than requested.
+    /// (deprecated) Returns a list of messages with database ID higher than requested.
     ///
     /// Blocked contacts and chats are excluded,
     /// but self-sent messages and contact requests are included in the results.
     ///
-    /// DEPRECATED 2026-04: This returns the message's id as soon as the first part arrives,
+    /// Deprecated 2026-04: This returns the message's id as soon as the first part arrives,
     /// even if it is not fully downloaded yet.
     /// The bot needs to wait for the message to be fully downloaded.
     /// Since this is usually not the desired behavior,
@@ -1201,7 +1201,7 @@ ORDER BY m.timestamp DESC,m.id DESC",
         Ok(list)
     }
 
-    /// Returns a list of messages with database ID higher than last marked as seen.
+    /// (deprecated) Returns a list of messages with database ID higher than last marked as seen.
     ///
     /// This function is supposed to be used by bot to request messages
     /// that are not processed yet.
@@ -1211,6 +1211,13 @@ ORDER BY m.timestamp DESC,m.id DESC",
     /// shortly after notification or notification is manually triggered
     /// to interrupt waiting.
     /// Notification may be manually triggered by calling [`Self::stop_io`].
+    ///
+    /// Deprecated 2026-04: This returns the message's id as soon as the first part arrives,
+    /// even if it is not fully downloaded yet.
+    /// The bot needs to wait for the message to be fully downloaded.
+    /// Since this is usually not the desired behavior,
+    /// bots should instead use the #DC_EVENT_INCOMING_MSG / [`EventType::IncomingMsg`]
+    /// event for getting notified about new messages.
     pub async fn wait_next_msgs(&self) -> Result<Vec<MsgId>> {
         self.new_msgs_notify.notified().await;
         let list = self.get_next_msgs().await?;