Update and clarify some docs

cc #1388, #1396

telethon/client/downloads.py

@@ -328,6 +328,13 @@ class DownloadMethods:
                 # or
                 path = await message.download_media()
                 await message.download_media(filename)
+
+                # Printing download progress
+                def callback(current, total):
+                    print('Downloaded', current, 'out of', total,
+                          'bytes: {:.2%}'.format(current / total))
+
+                await client.download_media(message, progress_callback=callback)
         """
         # TODO This won't work for messageService
         if isinstance(message, types.Message):
@@ -373,6 +380,11 @@ class DownloadMethods:
         """
         Low-level method to download files from their input location.
 
+        .. note::
+
+            Generally, you should instead use `download_media`.
+            This method is intended to be a bit more low-level.
+
         Arguments
             input_location (:tl:`InputFileLocation`):
                 The file location from which the file will be downloaded.

telethon/client/uploads.py

@@ -261,6 +261,13 @@ class UploadMethods:
                     '/my/photos/holiday2.jpg',
                     '/my/drawings/portrait.png'
                 ])
+
+                # Printing upload progress
+                def callback(current, total):
+                    print('Uploaded', current, 'out of', total,
+                          'bytes: {:.2%}'.format(current / total))
+
+                await client.send_file(chat, file, progress_callback=callback)
         """
         # TODO Properly implement allow_cache to reuse the sha256 of the file
         # i.e. `None` was used
@@ -436,6 +443,10 @@ class UploadMethods:
         """
         Uploads a file to Telegram's servers, without sending it.
 
+        .. note::
+
+            Generally, you want to use `send_file` instead.
+
         This method returns a handle (an instance of :tl:`InputFile` or
         :tl:`InputFileBig`, as required) which can be later used before
         it expires (they are usable during less than a day).