Add a description to the examples

Author: python273

examples/capthca_handle.py

@@ -9,6 +9,12 @@
 
 
 def captcha_handler(captcha):
+    """
+        При возникновении капчи вызывается эта функция и ей передается объект
+        капчи. Через метод get_url можно получить ссылку на изображение.
+        Через метод try_again можно попытаться отправить запрос с кодом капчи
+    """
+
     key = input("Enter Captcha {0}: ".format(captcha.get_url())).strip()
 
     # Пробуем снова отправить запрос с капчей
@@ -21,7 +27,7 @@ def main():
     login, password = 'python@vk.com', 'mypassword'
     vk = vk_api.VkApi(
         login, password,
-        captcha_handler=captcha_handler  # function for handle captcha
+        captcha_handler=captcha_handler  # функция для обработки капчи
     )
 
     try:

examples/get_full_wall.py

@@ -21,8 +21,16 @@ def main():
         return
 
     tools = vk_api.VkTools(vk)
-
-    wall = tools.get_all('wall.get', 100, {'owner_id': '183433824'})
+    """
+        VkTools.get_all позволяет получить все итемы, например со стены или
+        получить все диалоги, или сообщения. При использовании get_all
+        сокращается количество запросов к API за счет метода execute в 25 раз.
+        Например за раз со стены можно получить 100 * 25 = 2500, где
+        100 - максимальное количество постов, которое можно получить за один
+        запрос.
+    """
+
+    wall = tools.get_all('wall.get', 100, {'owner_id': 1})
     print('Posts count:', wall['count'])
 
     if wall['count']:

examples/simple_example.py

@@ -20,10 +20,13 @@ def main():
         print(error_msg)
         return
 
-    values = {
-        'count': 1  # Получаем только один пост
-    }
-    response = vk.method('wall.get', values)  # Используем метод wall.get
+    """
+        VkApi.method позволяет выполнять запросы к API. В этом примере
+        используется метод wall.get (https://vk.com/dev/wall.get) с параметром
+        count = 1, т.е. мы получаем один последний пост со стены текущего
+        пользователя.
+    """
+    response = vk.method('wall.get', {'count': 1})  # Используем метод wall.get
 
     if response['items']:
         print(response['items'][0])

examples/upload_photo.py

@@ -20,18 +20,23 @@ def main():
         print(error_msg)
         return
 
+    """
+        В VkUpload реализованы методы загрузки файлов в ВК.
+        (Не все, если что-то понадобится - могу дописать)
+    """
     upload = vk_api.VkUpload(vk)
-    photo = upload.photo(  # Подставте свои данные
+
+    photo = upload.photo(  # Подставьте свои данные
         'D:/downloads/tube.jpg',
         album_id=200851098,
         group_id=74030368
     )
 
-    vk_url = 'https://vk.com/photo{}_{}'.format(
+    vk_photo_url = 'https://vk.com/photo{}_{}'.format(
         photo[0]['owner_id'], photo[0]['id']
     )
 
-    print(photo, '\nLink: ', vk_url)
+    print(photo, '\nLink: ', vk_photo_url)
 
 if __name__ == '__main__':
     main()