From b39b6241b5782170ab3a0a9eb40dc7a280a2429f Mon Sep 17 00:00:00 2001
From: Leandro Toledo <leandrotoledodesouza@gmail.com>
Date: Wed, 8 Jul 2015 17:58:50 -0300
Subject: [PATCH] Updating README and minor fixes

---
 README.rst        | 51 ++++++++++++++++++++++++++++++++++++++++++++++-
 telegram/bot.py   |  6 ++----
 tests/test_bot.py |  5 ++---
 3 files changed, 54 insertions(+), 8 deletions(-)

diff --git a/README.rst b/README.rst
index f7e5a83d1..a247552e5 100644
--- a/README.rst
+++ b/README.rst
@@ -51,7 +51,13 @@ View the last release API documentation at: https://core.telegram.org/bots/api
 API
 ---
 
-The API is exposed via the ``telegram.Bot`` class::
+The API is exposed via the ``telegram.Bot`` class.
+
+To generate an Access Token you have to talk to `BotFather https://telegram.me/botfather`_ and follow a few simple steps (described `here https://core.telegram.org/bots#botfather`_).
+
+For full details see the `Bots: An introduction for developers <https://core.telegram.org/bots>`_.
+
+To create an instance of the ``telegram.Bot``::
 
     >>> import telegram
     >>> bot = telegram.Bot(token='token')
@@ -62,3 +68,46 @@ To see if your credentials are successful::
     {"first_name": "Toledo's Palace Bot", "username": "ToledosPalaceBot"}
 
 **NOTE**: much more than the small sample given here will print
+
+Bots can't initiate conversations with users. A user must either add them to a group or send them a message first. People can use ``telegram.me/<bot_username>`` links or username search to find your bot.
+
+To fetch text messages sent to your Bot::
+
+    >>> updates = bot.getUpdates()
+    >>> print [u.message.text for u in updates]
+
+To fetch images sent to your Bot::
+
+    >>> updates = bot.getUpdates()
+    >>> print [u.message.photo for u in updates if u.message.photo]
+
+To post a text message (you'll always need chat_id to reply users)::
+
+    >>> chat_id = bot.getUpdates()[-1].message.chat_id
+    >>> bot.sendMessage(chat_id=chat_id, text=u"I'm sorry Dave I'm afraid I can't do that.")
+
+To post a audio file (you'll always need chat_id to reply users)::
+
+    >>> chat_id = bot.getUpdates()[-1].message.chat_id
+    >>> bot.sendAudio(chat_id=chat_id, audio=open('tests/telegram.ogg', 'rb'))
+
+To tell the user that something is happening on bot's side::
+
+    >>> chat_id = bot.getUpdates()[-1].message.chat_id
+    >>> bot.sendChatAction(chat_id=chat_id, action=telegram.ChatAction.TYPING)
+
+There are many more API methods, to read the full API documentation::
+
+    $ pydoc telegram.Bot
+
+----
+TODO
+----
+
+Patches and bug reports are `welcome <https://github.com/leandrotoledo/python-telegram-bot/issues/new>`_, just please keep the style consistent with the original source.
+
+Add more example scripts.
+
+Add `custom keyboards <https://core.telegram.org/bots#keyboards>`_ methods.
+
+Add commands handler.
diff --git a/telegram/bot.py b/telegram/bot.py
index a95fb940c..4d5f6bd50 100644
--- a/telegram/bot.py
+++ b/telegram/bot.py
@@ -50,6 +50,8 @@ class Bot(object):
         return self._username
 
     def clearCredentials(self):
+        """Clear any credentials for this instance.
+        """
         self.__auth = False
 
     def getMe(self):
@@ -439,9 +441,6 @@ class Bot(object):
             - ChatAction.UPLOAD_AUDIO or upload_audio for audio files,
             - ChatAction.UPLOAD_DOCUMENT for general files,
             - ChatAction.FIND_LOCATION for location data.
-
-        Returns:
-          ?
         """
 
         url = '%s/sendChatAction' % (self.base_url)
@@ -539,7 +538,6 @@ class Bot(object):
         if not self.__auth:
             raise TelegramError({'message': "API must be authenticated."})
 
-
     def _requestUrl(self,
                     url,
                     method,
diff --git a/tests/test_bot.py b/tests/test_bot.py
index 5ef95a438..68d835255 100644
--- a/tests/test_bot.py
+++ b/tests/test_bot.py
@@ -112,9 +112,8 @@ class BotTest(unittest.TestCase):
     def testSendChatAction(self):
         '''Test the telegram.Bot sendChatAction method'''
         print 'Testing sendChatAction - ChatAction.TYPING'
-        message = self._bot.sendChatAction(action=telegram.ChatAction.TYPING,
-                                           chat_id=12173560)
-        # TODO: return json
+        self._bot.sendChatAction(action=telegram.ChatAction.TYPING,
+                                 chat_id=12173560)
 
     def testGetUserProfilePhotos(self):
         '''Test the telegram.Bot getUserProfilePhotos method'''