Update documentation with intersphinx and better summaries

telethon/events/callbackquery.py

@@ -10,7 +10,8 @@ from ..tl.custom.sendergetter import SenderGetter
 @name_inner_event
 class CallbackQuery(EventBuilder):
     """
-    Represents a callback query event (when an inline button is clicked).
+    Occurs whenever you sign in as a bot and a user
+    clicks one of the inline buttons on your messages.
 
     Note that the `chats` parameter will **not** work with normal
     IDs or peers if the clicked inline button comes from a "via bot"

telethon/events/chataction.py

@@ -6,7 +6,7 @@ from ..tl import types, functions
 @name_inner_event
 class ChatAction(EventBuilder):
     """
-    Represents an action in a chat (such as user joined, left, or new pin).
+    Occurs whenever a user joins or leaves a chat, or a message is pinned.
     """
     @classmethod
     def build(cls, update):

telethon/events/inlinequery.py

@@ -12,7 +12,8 @@ from ..tl.custom.sendergetter import SenderGetter
 @name_inner_event
 class InlineQuery(EventBuilder):
     """
-    Represents an inline query event (when someone writes ``'@my_bot query'``).
+    Occurs whenever you sign in as a bot and a user
+    sends an inline query such as ``@bot query``.
 
     Args:
         users (`entity`, optional):

telethon/events/messagedeleted.py

@@ -5,7 +5,9 @@ from ..tl import types
 @name_inner_event
 class MessageDeleted(EventBuilder):
     """
-    Event fired when one or more messages are deleted.
+    Occurs whenever a message is deleted. Note that this event isn't 100%
+    reliable, since Telegram doesn't always notify the clients that a message
+    was deleted.
 
     .. important::
 

telethon/events/messageedited.py

@@ -6,7 +6,9 @@ from ..tl import types
 @name_inner_event
 class MessageEdited(NewMessage):
     """
-    Event fired when a message has been edited.
+    Occurs whenever a message is edited. Just like `NewMessage
+    <telethon.events.newmessage.NewMessage>`, you should treat
+    this event as a `Message <telethon.tl.custom.message.Message>`.
 
     .. warning::
 

telethon/events/messageread.py

@@ -6,7 +6,7 @@ from ..tl import types
 @name_inner_event
 class MessageRead(EventBuilder):
     """
-    Event fired when one or more messages have been read.
+    Occurs whenever one or more messages are read in a chat.
 
     Args:
         inbox (`bool`, optional):

telethon/events/newmessage.py

@@ -8,7 +8,7 @@ from ..tl import types
 @name_inner_event
 class NewMessage(EventBuilder):
     """
-    Represents a new message event builder.
+    Occurs whenever a new text message or a message with media arrives.
 
     Args:
         incoming (`bool`, optional):

telethon/events/raw.py

@@ -4,7 +4,9 @@ from .. import utils
 
 class Raw(EventBuilder):
     """
-    Represents a raw event. The event is the update itself.
+    Raw events are not actual events. Instead, they are the raw
+    :tl:`Update` object that Telegram sends. You normally shouldn't
+    need these.
 
     Args:
         types (`list` | `tuple` | `type`, optional):

telethon/events/userupdate.py

@@ -9,7 +9,7 @@ from ..tl.custom.sendergetter import SenderGetter
 @name_inner_event
 class UserUpdate(EventBuilder):
     """
-    Represents a user update (gone online, offline, joined Telegram).
+    Occurs whenever a user goes online, starts typing, etc.
     """
     @classmethod
     def build(cls, update):
@@ -32,7 +32,8 @@ class UserUpdate(EventBuilder):
 
     class Event(EventCommon, SenderGetter):
         """
-        Represents the event of a user status update (last seen, joined).
+        Represents the event of a user update
+        such as gone online, started typing, etc.
 
         Members:
             online (`bool`, optional):