Doc Fixes/Additions (#2094)

* Add notes on thumbs being ignored for small video files

* Fix some cross refs

* Add not to DictPersistence about it not actually writing to file

* Fix reply_to_message docs of Message

telegram/bot.py

@@ -751,8 +751,11 @@ class Bot(TelegramObject):
         the future.
 
         Note:
-            The video argument can be either a file_id, an URL or a file from disk
+            * The video argument can be either a file_id, an URL or a file from disk
               ``open(filename, 'rb')``
+            * ``thumb`` will be ignored for small video files, for which Telegram can easily
+              generate thumb nails. However, this behaviour is undocumented and might be changed
+              by Telegram.
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@@ -841,8 +844,11 @@ class Bot(TelegramObject):
         Use this method to send video messages.
 
         Note:
-            The video_note argument can be either a file_id or a file from disk
+            * The video_note argument can be either a file_id or a file from disk
               ``open(filename, 'rb')``
+            * ``thumb`` will be ignored for small video files, for which Telegram can easily
+              generate thumb nails. However, this behaviour is undocumented and might be changed
+              by Telegram.
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@@ -919,6 +925,11 @@ class Bot(TelegramObject):
         Bots can currently send animation files of up to 50 MB in size, this limit may be changed
         in the future.
 
+        Note:
+            ``thumb`` will be ignored for small files, for which Telegram can easily
+            generate thumb nails. However, this behaviour is undocumented and might be changed
+            by Telegram.
+
         Args:
             chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
                 of the target channel (in the format @channelusername).

telegram/ext/dictpersistence.py

@@ -33,6 +33,12 @@ from telegram.ext import BasePersistence
 class DictPersistence(BasePersistence):
     """Using python's dicts and json for making your bot persistent.
 
+    Note:
+        This class does *not* implement a :meth:`flush` method, meaning that data managed by
+        ``DictPersistence`` is in-memory only and will be lost when the bot shuts down. This is,
+        because ``DictPersistence`` is mainly intended as starting point for custom persistence
+        classes that need to JSON-serialize the stored data before writing them to file/database.
+
     Attributes:
         store_user_data (:obj:`bool`): Whether user_data should be saved by this
             persistence class.

telegram/files/inputmedia.py

@@ -181,9 +181,12 @@ class InputMediaVideo(InputMedia):
             Thumbnails can't be reused and can be only uploaded as a new file.
 
     Note:
-        When using a :class:`telegram.Video` for the :attr:`media` attribute. It will take the
+        *  When using a :class:`telegram.Video` for the :attr:`media` attribute. It will take the
            width, height and duration from that video, unless otherwise specified with the optional
            arguments.
+        *  ``thumb`` will be ignored for small video files, for which Telegram can easily
+           generate thumb nails. However, this behaviour is undocumented and might be changed
+           by Telegram.
     """
 
     def __init__(self, media, caption=None, width=None, height=None, duration=None,

telegram/message.py

@@ -47,7 +47,9 @@ class Message(TelegramObject):
         forward_from_message_id (:obj:`int`): Optional. Identifier of the original message in the
             channel.
         forward_date (:class:`datetime.datetime`): Optional. Date the original message was sent.
-        reply_to_message (:class:`telegram.Message`): Optional. The original message.
+        reply_to_message (:class:`telegram.Message`): Optional. For replies, the original message.
+            Note that the Message object in this field will not contain further
+            ``reply_to_message`` fields even if it itself is a reply.
         edit_date (:class:`datetime.datetime`): Optional. Date the message was last edited.
         media_group_id (:obj:`str`): Optional. The unique identifier of a media message group this
             message belongs to.
@@ -132,8 +134,6 @@ class Message(TelegramObject):
         forward_date (:class:`datetime.datetime`, optional): For forwarded messages, date the
             original message was sent in Unix time. Converted to :class:`datetime.datetime`.
         reply_to_message (:class:`telegram.Message`, optional): For replies, the original message.
-            Note that the Message object in this field will not contain further
-            ``reply_to_message`` fields even if it itself is a reply.
         edit_date (:class:`datetime.datetime`, optional): Date the message was last edited in Unix
             time. Converted to :class:`datetime.datetime`.
         media_group_id (:obj:`str`, optional): The unique identifier of a media message group this
@@ -142,7 +142,7 @@ class Message(TelegramObject):
             characters. Also found as :attr:`telegram.constants.MAX_MESSAGE_LENGTH`.
         entities (List[:class:`telegram.MessageEntity`], optional): For text messages, special
             entities like usernames, URLs, bot commands, etc. that appear in the text. See
-            attr:`parse_entity` and attr:`parse_entities` methods for how to use properly.
+            :attr:`parse_entity` and :attr:`parse_entities` methods for how to use properly.
         caption_entities (List[:class:`telegram.MessageEntity`]): Optional. For Messages with a
             Caption. Special entities like usernames, URLs, bot commands, etc. that appear in the
             caption. See :attr:`Message.parse_caption_entity` and :attr:`parse_caption_entities`
@@ -191,7 +191,7 @@ class Message(TelegramObject):
         channel_chat_created (:obj:`bool`, optional): Service message: The channel has been
             created. This field can't be received in a message coming through updates, because bot
             can't be a member of a channel when it is created. It can only be found in
-            attr:`reply_to_message` if someone replies to a very first message in a channel.
+            :attr:`reply_to_message` if someone replies to a very first message in a channel.
         migrate_to_chat_id (:obj:`int`, optional): The group has been migrated to a supergroup with
             the specified identifier. This number may be greater than 32 bits and some programming
             languages may have difficulty/silent defects in interpreting it. But it is smaller than