Document the behavior of captions for media groups

As discussed in #987, the current behavior of captions regarding media
groups is documented in neither teloxide nor the Telegram API[0]. Users
of the official telegram clients may expect to be able to set what
appears to them as a "global" caption on media groups, when such a thing
does not actually exist in the API, and is just the result of how
official clients render media groups with only one captioned
`InputMedia`.

This commit changes the schema which auto-generates payload types, as
well as introduces the changes induced to the documentation of
`SendMediaGroup`.

Fix #987.

Links:
[0]: https://core.telegram.org/bots/api#sendmediagroup

Signed-off-by: Lymkwi <lymkwi@vulpinecitrus.info>

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Documentation regarding the way captions work for the official clients on `SendMediaGroup` ([PR 992](https://github.com/teloxide/teloxide/pull/992))
 - Add `MessageToCopyNotFound` error to `teloxide::errors::ApiError` ([PR 917](https://github.com/teloxide/teloxide/pull/917)) 
 - `Dispatcher::try_dispatch_with_listener` ([PR 913](https://github.com/teloxide/teloxide/pull/913))
 - Missing Message::filter_* functions ([PR 982](https://github.com/teloxide/teloxide/pull/982)): 

crates/teloxide-core/schema.ron

@@ -1118,8 +1118,8 @@ Schema(
             names: ("sendMediaGroup", "SendMediaGroup", "send_media_group"),
             return_ty: ArrayOf(RawTy("Message")),
             doc: Doc(
-                md: "Use this method to send a group of photos, videos, documents or audios as an album. Documents and audio files can be only grouped in an album with messages of the same type. On success, an array of [Message]s that were sent is returned.",
-                md_links: {"Message": "https://core.telegram.org/bots/api#message"},
+                md: "Use this method to send a group of photos, videos, documents or audios as an album. Documents and audio files can be only grouped in an album with messages of the same type. On success, an array of [Message]s that were sent is returned.\n\n## Captions\n\nYou may want to set a \"global\" caption which renders in the message, underneath the set of media. However, global captions for a media group are not part of the Telegram API. They result from how the official clients (at least) render a media group where only one [InputMedia] has a caption set. That captioned [InputMedia] may be in any position of the group.\n\nIn order to set a \"global\" caption of a media group, set a caption for a single [InputMedia] in the group with the contents you wish to display underneath all media.\n\nIf multiple [InputMedia] have captions, including identical ones, the official clients will not render a global caption underneath the group. Each individual media will keep its own caption however, which can be shown by the client when viewing the media individually, or by separating the media in its own message (for example by forwarding a single media from the media group).",
+                md_links: {"Message": "https://core.telegram.org/bots/api#message", "InputMedia": "https://core.telegram.org/bots/api#input_media"},
             ),
             tg_doc: "https://core.telegram.org/bots/api#sendmediagroup",
             tg_category: "Available methods",

crates/teloxide-core/src/payloads/send_media_group.rs

@@ -7,7 +7,16 @@ use crate::types::{InputMedia, Message, MessageId, Recipient, ThreadId};
 impl_payload! {
     /// Use this method to send a group of photos, videos, documents or audios as an album. Documents and audio files can be only grouped in an album with messages of the same type. On success, an array of [`Message`]s that were sent is returned.
     ///
+    /// ## Captions
+    ///
+    /// You may want to set a "global" caption which renders in the message, underneath the set of media. However, global captions for a media group are not part of the Telegram API. They result from how the official clients (at least) render a media group where only one [`InputMedia`] has a caption set. That captioned [`InputMedia`] may be in any position of the group.
+    ///
+    /// In order to set a "global" caption of a media group, set a caption for a single [`InputMedia`] in the group with the contents you wish to display underneath all media.
+    ///
+    /// If multiple [`InputMedia`] have captions, including identical ones, the official clients will not render a global caption underneath the group. Each individual media will keep its own caption however, which can be shown by the client when viewing the media individually, or by separating the media in its own message (for example by forwarding a single media from the media group).
+    ///
     /// [`Message`]: crate::types::Message
+    /// [`InputMedia`]: crate::types::InputMedia
     #[derive(Debug, Clone, Serialize)]
     pub SendMediaGroup (SendMediaGroupSetters) => Vec<Message> {
         required {