Add missing documentation for telethon.tl.custom and crosslinks

telethon/tl/custom/dialog.py

@@ -7,7 +7,47 @@ class Dialog:
     Custom class that encapsulates a dialog (an open "conversation" with
     someone, a group or a channel) providing an abstraction to easily
     access the input version/normal entity/message etc. The library will
-    return instances of this class when calling `client.get_dialogs()`.
+    return instances of this class when calling :meth:`.get_dialogs()`.
+
+    Args:
+        dialog (:obj:`Dialog`):
+            The original ``Dialog`` instance.
+
+        pinned (:obj:`bool`):
+            Whether this dialog is pinned to the top or not.
+
+        message (:obj:`Message`):
+            The last message sent on this dialog. Note that this member
+            will not be updated when new messages arrive, it's only set
+            on creation of the instance.
+
+        date (:obj:`datetime`):
+            The date of the last message sent on this dialog.
+
+        entity (:obj:`entity`):
+            The entity that belongs to this dialog (user, chat or channel).
+
+        input_entity (:obj:`InputPeer`):
+            Input version of the entity.
+
+        id (:obj:`int`):
+            The marked ID of the entity, which is guaranteed to be unique.
+
+        name (:obj:`str`):
+            Display name for this dialog. For chats and channels this is
+            their title, and for users it's "First-Name Last-Name".
+
+        unread_count (:obj:`int`):
+            How many messages are currently unread in this dialog. Note that
+            this value won't update when new messages arrive.
+
+        unread_mentions_count (:obj:`int`):
+            How many mentions are currently unread in this dialog. Note that
+            this value won't update when new messages arrive.
+
+        draft (:obj:`telethon.tl.custom.draft.Draft`):
+            The draft object in this dialog. It will not be ``None``,
+            so you can call ``draft.set_message(...)``.
     """
     def __init__(self, client, dialog, entities, messages):
         # Both entities and messages being dicts {ID: item}
@@ -19,6 +59,7 @@ class Dialog:
 
         self.entity = entities[utils.get_peer_id(dialog.peer)]
         self.input_entity = utils.get_input_peer(self.entity)
+        self.id = utils.get_peer_id(self.input_entity)
         self.name = utils.get_display_name(self.entity)
 
         self.unread_count = dialog.unread_count
@@ -29,6 +70,6 @@ class Dialog:
     def send_message(self, *args, **kwargs):
         """
         Sends a message to this dialog. This is just a wrapper around
-        client.send_message(dialog.input_entity, *args, **kwargs).
+        ``client.send_message(dialog.input_entity, *args, **kwargs)``.
         """
         return self._client.send_message(self.input_entity, *args, **kwargs)

telethon/tl/custom/draft.py

@@ -1,3 +1,5 @@
+import datetime
+
 from ..functions.messages import SaveDraftRequest
 from ..types import UpdateDraftMessage, DraftMessage
 from ...extensions import markdown
@@ -7,7 +9,17 @@ class Draft:
     """
     Custom class that encapsulates a draft on the Telegram servers, providing
     an abstraction to change the message conveniently. The library will return
-    instances of this class when calling ``client.get_drafts()``.
+    instances of this class when calling :meth:`get_drafts()`.
+
+    Args:
+        date (:obj:`datetime`):
+            The date of the draft.
+
+        link_preview (:obj:`bool`):
+            Whether the link preview is enabled or not.
+
+        reply_to_msg_id (:obj:`int`):
+            The message ID that the draft will reply to.
     """
     def __init__(self, client, peer, draft):
         self._client = client
@@ -33,20 +45,41 @@ class Draft:
 
     @property
     def entity(self):
+        """
+        The entity that belongs to this dialog (user, chat or channel).
+        """
         return self._client.get_entity(self._peer)
 
     @property
     def input_entity(self):
+        """
+        Input version of the entity.
+        """
         return self._client.get_input_entity(self._peer)
 
     @property
     def text(self):
+        """
+        The markdown text contained in the draft. It will be
+        empty if there is no text (and hence no draft is set).
+        """
         return self._text
 
     @property
     def raw_text(self):
+        """
+        The raw (text without formatting) contained in the draft.
+        It will be empty if there is no text (thus draft not set).
+        """
         return self._raw_text
 
+    @property
+    def is_empty(self):
+        """
+        Convenience bool to determine if the draft is empty or not.
+        """
+        return not self._text
+
     def set_message(self, text=None, reply_to=0, parse_mode='md',
                     link_preview=None):
         """
@@ -88,10 +121,15 @@ class Draft:
             self._raw_text = raw_text
             self.link_preview = link_preview
             self.reply_to_msg_id = reply_to
+            self.date = datetime.datetime.now()
 
         return result
 
     def send(self, clear=True, parse_mode='md'):
+        """
+        Sends the contents of this draft to the dialog. This is just a
+        wrapper around send_message(dialog.input_entity, *args, **kwargs).
+        """
         self._client.send_message(self._peer, self.text,
                                   reply_to=self.reply_to_msg_id,
                                   link_preview=self.link_preview,
@@ -100,7 +138,6 @@ class Draft:
 
     def delete(self):
         """
-        Deletes this draft
-        :return bool: ``True`` on success
+        Deletes this draft, and returns ``True`` on success.
         """
         return self.set_message(text='')