Update and improve documentation for API.create_block

Automatically use docstring for documentation
Improve method and documentation order
Add include_entities and skip_status parameters to documentation
Remove id parameter from documentation
Update method/endpoint documentation

diff --git a/docs/api.rst b/docs/api.rst
index 7c76c679ed93c50dfbc11215ca9c778383a05c08..96141ceb3caf5790849723d0569d20704298e2a5 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -179,6 +179,8 @@ Mute, block, and report users
 
 .. automethod:: API.mutes
 
+.. automethod:: API.create_block
+
 
 Direct Message Methods
 ----------------------
@@ -253,17 +255,6 @@ Account Methods
 Block Methods
 -------------
 
-.. method:: API.create_block(id/screen_name/user_id)
-
-   Blocks the user specified in the ID parameter as the authenticating user.
-   Destroys a friendship to the blocked user if it exists.
-
-   :param id: |uid|
-   :param screen_name: |screen_name|
-   :param user_id: |user_id|
-   :rtype: :class:`User` object
-
-
 .. method:: API.destroy_block(id/screen_name/user_id)
 
    Un-blocks the user specified in the ID parameter for the authenticating

diff --git a/tweepy/api.py b/tweepy/api.py
index 380923d40890f7648432395e3fbd01c3c512e466..b543e543b95cfc41cfd38cf05ba28dc0914a30b2 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -2091,6 +2091,30 @@ class API:
             ), **kwargs
         )
 
+    @payload('user')
+    def create_block(self, **kwargs):
+        """create_block(*, screen_name, user_id, include_entities, skip_status)
+
+        Blocks the specified user from following the authenticating user. In
+        addition the blocked user will not show in the authenticating users
+        mentions or timeline (unless retweeted by another user). If a follow or
+        friend relationship exists it is destroyed.
+
+        :param screen_name: |screen_name|
+        :param user_id: |user_id|
+        :param include_entities: |include_entities|
+        :param skip_status: |skip_status|
+
+        :rtype: :class:`User` object
+
+        :reference: https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-blocks-create
+        """
+        return self.request(
+            'POST', 'blocks/create', endpoint_parameters=(
+                'screen_name', 'user_id', 'include_entities', 'skip_status'
+            ), **kwargs
+        )
+
     def media_upload(self, filename, *, file=None, chunked=False,
                      media_category=None, additional_owners=None, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/overview
@@ -2330,16 +2354,6 @@ class API:
             ), use_cache=False, **kwargs
         )
 
-    @payload('user')
-    def create_block(self, **kwargs):
-        """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-blocks-create
-        """
-        return self.request(
-            'POST', 'blocks/create', endpoint_parameters=(
-                'screen_name', 'user_id', 'include_entities', 'skip_status'
-            ), **kwargs
-        )
-
     @payload('user')
     def destroy_block(self, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/post-blocks-destroy