twitter 8.2.0 → 8.3.1

data/lib/twitter/rest/lists.rb

@@ -1,4 +1,3 @@
-require "addressable/uri"
 require "twitter/arguments"
 require "twitter/cursor"
 require "twitter/error"
@@ -12,17 +11,23 @@ require "uri"
 
 module Twitter
   module REST
+    # Methods for working with Twitter lists
     module Lists
       include Twitter::REST::Utils
       include Twitter::Utils
+
+      # Maximum users per request
       MAX_USERS_PER_REQUEST = 100
 
-      # Returns all lists the authenticating or specified user subscribes to, including their own
+      # Returns all lists the user subscribes to, including their own
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/lists/list
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.lists
       # @return [Array<Twitter::List>]
       # @overload lists(options = {})
       #   @param options [Hash] A customizable set of options.
@@ -32,17 +37,23 @@ module Twitter
       #   @param options [Hash] A customizable set of options.
       #   @option options [Boolean] :reverse Set this to true if you would like owned lists to be returned first.
       def lists(*args)
-        objects_from_response_with_user(Twitter::List, :get, "/1.1/lists/list.json", args)
+        objects_from_response_with_user(List, :get, "/1.1/lists/list.json", args)
       end
-      alias lists_subscribed_to lists
+      # @!method lists_subscribed_to
+      #   @api public
+      #   @see #lists
+      alias_method :lists_subscribed_to, :lists
 
-      # Show tweet timeline for members of the specified list
+      # Shows tweet timeline for members of the specified list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/lists/statuses
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.list_timeline('twitter-engineering')
       # @return [Array<Twitter::Tweet>]
       # @overload list_timeline(list, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -58,19 +69,22 @@ module Twitter
       #   @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
       #   @option options [Integer] :count The number of results to retrieve.
       def list_timeline(*args)
-        arguments = Twitter::Arguments.new(args)
+        arguments = Arguments.new(args)
         merge_list!(arguments.options, arguments.pop)
         merge_owner!(arguments.options, arguments.pop)
-        perform_get_with_objects("/1.1/lists/statuses.json", arguments.options, Twitter::Tweet)
+        perform_get_with_objects("/1.1/lists/statuses.json", arguments.options, Tweet)
       end
 
       # Removes the specified member from the list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/lists/members/destroy
       # @rate_limited No
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.remove_list_member('twitter-engineering', 'sferik')
       # @return [Twitter::List] The list.
       # @overload remove_list_member(list, user_to_remove, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -85,12 +99,15 @@ module Twitter
         list_from_response_with_user("/1.1/lists/members/destroy.json", args)
       end
 
-      # List the lists the specified user has been added to
+      # Lists the lists the specified user has been added to
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/lists/memberships
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.memberships
       # @return [Twitter::Cursor]
       # @overload memberships(options = {})
       #   @param options [Hash] A customizable set of options.
@@ -102,16 +119,19 @@ module Twitter
       #   @option options [Integer] :count The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.
       #   @option options [Boolean, String, Integer] :filter_to_owned_lists When set to true, t or 1, will return just lists the authenticating user owns, and the user represented by user_id or screen_name is a member of.
       def memberships(*args)
-        cursor_from_response_with_user(:lists, Twitter::List, "/1.1/lists/memberships.json", args)
+        cursor_from_response_with_user(:lists, List, "/1.1/lists/memberships.json", args)
       end
 
       # Returns the subscribers of the specified list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/lists/subscribers
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.list_subscribers('twitter-engineering')
       # @return [Twitter::Cursor] The subscribers of the specified list.
       # @overload list_subscribers(list, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -124,13 +144,16 @@ module Twitter
         cursor_from_response_with_list("/1.1/lists/subscribers.json", args)
       end
 
-      # Make the authenticated user follow the specified list
+      # Makes the authenticated user follow the specified list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/lists/subscribers/create
       # @rate_limited No
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.list_subscribe('twitter-engineering')
       # @return [Twitter::List] The specified list.
       # @overload list_subscribe(list, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -143,13 +166,16 @@ module Twitter
         list_from_response(:post, "/1.1/lists/subscribers/create.json", args)
       end
 
-      # Check if a user is a subscriber of the specified list
+      # Checks if a user is a subscriber of the specified list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/lists/subscribers/show
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.list_subscriber?('twitter-engineering', 'sferik')
       # @return [Boolean] true if user is a subscriber of the specified list, otherwise false.
       # @overload list_subscriber?(list, user_to_check, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -165,13 +191,16 @@ module Twitter
         list_user?(:get, "/1.1/lists/subscribers/show.json", args)
       end
 
-      # Unsubscribes the authenticated user form the specified list
+      # Unsubscribes the authenticated user from the specified list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/lists/subscribers/destroy
       # @rate_limited No
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.list_unsubscribe('twitter-engineering')
       # @return [Twitter::List] The specified list.
       # @overload list_unsubscribe(list, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -186,13 +215,16 @@ module Twitter
 
       # Adds specified members to a list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/lists/members/create_all
-      # @note Lists are limited to having 5,000 members, and you are limited to adding up to 100 members to a list at a time with this method.
+      # @note Lists are limited to having 5,000 members.
       # @rate_limited No
       # @authentication Requires user context
       # @raise [Twitter::Error::Forbidden] Error raised when user has already been added.
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.add_list_members('twitter-engineering', ['sferik', 'pengwynn'])
       # @return [Twitter::List] The list.
       # @overload add_list_members(list, users, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -207,13 +239,16 @@ module Twitter
         list_from_response_with_users("/1.1/lists/members/create_all.json", args)
       end
 
-      # Check if a user is a member of the specified list
+      # Checks if a user is a member of the specified list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/lists/members/show
       # @authentication Requires user context
       # @rate_limited Yes
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.list_member?('twitter-engineering', 'sferik')
       # @return [Boolean] true if user is a member of the specified list, otherwise false.
       # @overload list_member?(list, user_to_check, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -230,11 +265,14 @@ module Twitter
 
       # Returns the members of the specified list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/lists/members
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.list_members('twitter-engineering')
       # @return [Twitter::Cursor]
       # @overload list_members(list, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -247,14 +285,17 @@ module Twitter
         cursor_from_response_with_list("/1.1/lists/members.json", args)
       end
 
-      # Add a member to a list
+      # Adds a member to a list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/lists/members/create
       # @note Lists are limited to having 5,000 members.
       # @rate_limited No
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.add_list_member('twitter-engineering', 'sferik')
       # @return [Twitter::List] The list.
       # @overload add_list_member(list, user_to_add, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -271,12 +312,15 @@ module Twitter
 
       # Deletes the specified list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/lists/destroy
       # @note Must be owned by the authenticated user.
       # @rate_limited No
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.destroy_list('twitter-engineering')
       # @return [Twitter::List] The deleted list.
       # @overload destroy_list(list, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -291,11 +335,14 @@ module Twitter
 
       # Updates the specified list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/lists/update
       # @rate_limited No
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.list_update('twitter-engineering', description: 'Tweeps')
       # @return [Twitter::List] The created list.
       # @overload list_update(list, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -314,28 +361,34 @@ module Twitter
 
       # Creates a new list for the authenticated user
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/lists/create
       # @note Accounts are limited to 20 lists.
       # @rate_limited No
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.create_list('twitter-engineering')
       # @return [Twitter::List] The created list.
       # @param name [String] The name for the list.
       # @param options [Hash] A customizable set of options.
       # @option options [String] :mode ('public') Whether your list is public or private. Values can be 'public' or 'private'.
       # @option options [String] :description The description to give the list.
       def create_list(name, options = {})
-        perform_post_with_object("/1.1/lists/create.json", options.merge(name:), Twitter::List)
+        perform_post_with_object("/1.1/lists/create.json", options.merge(name:), List)
       end
 
-      # Show the specified list
+      # Shows the specified list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/lists/show
-      # @note Private lists will only be shown if the authenticated user owns the specified list.
+      # @note Private lists are only shown if the authenticated user owns them.
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.list('twitter-engineering')
       # @return [Twitter::List] The specified list.
       # @overload list(list, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -348,12 +401,15 @@ module Twitter
         list_from_response(:get, "/1.1/lists/show.json", args)
       end
 
-      # List the lists the specified user follows
+      # Lists the lists the specified user follows
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/lists/subscriptions
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.subscriptions
       # @return [Twitter::Cursor]
       # @overload subscriptions(options = {})
       #   @param options [Hash] A customizable set of options.
@@ -361,16 +417,19 @@ module Twitter
       #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
       #   @param options [Hash] A customizable set of options.
       def subscriptions(*args)
-        cursor_from_response_with_user(:lists, Twitter::List, "/1.1/lists/subscriptions.json", args)
+        cursor_from_response_with_user(:lists, List, "/1.1/lists/subscriptions.json", args)
       end
 
       # Removes specified members from the list
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/lists/members/destroy_all
       # @rate_limited No
       # @authentication Requires user context
       # @raise [Twitter::Error::NotFound] Error raised when supplied list is not found.
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.remove_list_members('twitter-engineering', ['sferik'])
       # @return [Twitter::List] The list.
       # @overload remove_list_members(list, users, options = {})
       #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
@@ -387,10 +446,13 @@ module Twitter
 
       # Returns the lists owned by the specified Twitter user
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/get/lists/ownerships
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.owned_lists
       # @return [Array<Twitter::List>]
       # @overload owned_lists(options = {})
       #   @param options [Hash] A customizable set of options.
@@ -400,78 +462,105 @@ module Twitter
       #   @param options [Hash] A customizable set of options.
       #   @option options [Integer] :count The amount of results to return per page. Defaults to 20. No more than 1000 results will ever be returned in a single page.
       def owned_lists(*args)
-        cursor_from_response_with_user(:lists, Twitter::List, "/1.1/lists/ownerships.json", args)
+        cursor_from_response_with_user(:lists, List, "/1.1/lists/ownerships.json", args)
       end
 
-    private
+      private
 
-      # @param request_method [Symbol]
-      # @param path [String]
-      # @param args [Array]
-      # @return [Array<Twitter::User>]
+      # Retrieves a list from the response
+      #
+      # @api private
+      # @return [Twitter::List]
       def list_from_response(request_method, path, args)
-        arguments = Twitter::Arguments.new(args)
+        arguments = Arguments.new(args)
         merge_list!(arguments.options, arguments.pop)
         merge_owner!(arguments.options, arguments.pop)
-        perform_request_with_object(request_method, path, arguments.options, Twitter::List)
+        perform_request_with_object(request_method, path, arguments.options, List)
       end
 
+      # Retrieves a cursor from the response with list
+      #
+      # @api private
+      # @return [Twitter::Cursor]
       def cursor_from_response_with_list(path, args)
-        arguments = Twitter::Arguments.new(args)
+        arguments = Arguments.new(args)
         merge_list!(arguments.options, arguments.pop)
         merge_owner!(arguments.options, arguments.pop)
-        perform_get_with_cursor(path, arguments.options, :users, Twitter::User)
+        perform_get_with_cursor(path, arguments.options, :users, User)
       end
 
+      # Checks if user is a member of a list
+      #
+      # @api private
+      # @return [Boolean]
       def list_user?(request_method, path, args)
-        arguments = Twitter::Arguments.new(args)
+        arguments = Arguments.new(args)
         merge_user!(arguments.options, arguments.pop)
         merge_list!(arguments.options, arguments.pop)
         merge_owner!(arguments.options, arguments.pop)
-        perform_request(request_method.to_sym, path, arguments.options)
+        perform_request(request_method, path, arguments.options)
         true
-      rescue Twitter::Error::Forbidden, Twitter::Error::NotFound
+      rescue Error::Forbidden, Error::NotFound
         false
       end
 
+      # Retrieves a list from response with user
+      #
+      # @api private
+      # @return [Twitter::List]
       def list_from_response_with_user(path, args)
-        arguments = Twitter::Arguments.new(args)
+        arguments = Arguments.new(args)
         merge_user!(arguments.options, arguments.pop)
         merge_list!(arguments.options, arguments.pop)
         merge_owner!(arguments.options, arguments.pop)
-        perform_post_with_object(path, arguments.options, Twitter::List)
+        perform_post_with_object(path, arguments.options, List)
       end
 
+      # Retrieves a list from response with users
+      #
+      # @api private
+      # @return [Twitter::List]
       def list_from_response_with_users(path, args)
-        arguments = args.dup
-        options = arguments.last.is_a?(::Hash) ? arguments.pop : {}
+        arguments = args
+        options = arguments.last.instance_of?(Hash) ? arguments.pop : {} # : Hash[Symbol, untyped]
         members = arguments.pop
         merge_list!(options, arguments.pop)
         merge_owner!(options, arguments.pop)
-        pmap(members.each_slice(MAX_USERS_PER_REQUEST)) do |users|
-          perform_post_with_object(path, merge_users(options, users), Twitter::List)
-        end.last
+        *, result = pmap(members.each_slice(MAX_USERS_PER_REQUEST)) do |users|
+          perform_post_with_object(path, merge_users(options, users), List)
+        end
+        result
       end
 
       # Take a list and merge it into the hash with the correct key
       #
+      # @api private
       # @param hash [Hash]
       # @param list [Integer, String, URI, Twitter::List] A Twitter list ID, slug, URI, or object.
+      # @return [void]
       def merge_list!(hash, list)
         case list
-        when Integer               then hash[:list_id] = list
-        when Twitter::List         then merge_list_and_owner!(hash, list)
-        when String                then merge_slug_and_owner!(hash, list)
-        when URI, Addressable::URI then merge_slug_and_owner!(hash, list.path)
+        when Integer then hash[:list_id] = list
+        when List then merge_list_and_owner!(hash, list)
+        when String then merge_slug_and_owner!(hash, list)
+        when URI then merge_slug_and_owner!(hash, list.path) # steep:ignore NoMethod
         end
       end
 
+      # Merges slug and owner into hash
+      #
+      # @api private
+      # @return [void]
       def merge_slug_and_owner!(hash, path)
         list = path.split("/")
         hash[:slug] = list.pop
         hash[:owner_screen_name] = list.pop unless list.empty?
       end
 
+      # Merges list and owner into hash
+      #
+      # @api private
+      # @return [void]
       def merge_list_and_owner!(hash, list)
         merge_list!(hash, list.id)
         merge_owner!(hash, list.user)
@@ -479,11 +568,12 @@ module Twitter
 
       # Take an owner and merge it into the hash with the correct key
       #
+      # @api private
       # @param hash [Hash]
       # @param user[Integer, String, Twitter::User] A Twitter user ID, screen_name, or object.
-      # @return [Hash]
+      # @return [void]
       def merge_owner!(hash, user)
-        return hash if hash[:owner_id] || hash[:owner_screen_name]
+        return if hash.key?(:owner_id) || hash.key?(:owner_screen_name)
 
         if user
           merge_user!(hash, user, "owner")
@@ -491,7 +581,6 @@ module Twitter
         else
           hash[:owner_id] = user_id
         end
-        hash
       end
     end
   end

data/lib/twitter/rest/oauth.rb

@@ -3,61 +3,67 @@ require "twitter/rest/utils"
 
 module Twitter
   module REST
+    # Methods for OAuth authentication
     module OAuth
       include Twitter::REST::Utils
 
-      # Allows a registered application to obtain an OAuth 2 Bearer Token, which can be used to make API requests
-      # on an application's own behalf, without a user context.
-      #
-      # Only one bearer token may exist outstanding for an application, and repeated requests to this method
-      # will yield the same already-existent token until it has been invalidated.
+      # Obtains an OAuth 2 Bearer Token for application-only auth
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/oauth2/token
       # @rate_limited No
       # @authentication Required
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.token
       # @return [String] The Bearer token.
       # @param options [Hash] A customizable set of options.
-      # @example Generate a Bearer Token
-      #   client = Twitter::REST::Client.new(consumer_key: 'abc', consumer_secret: 'def')
-      #   bearer_token = client.token
       def token(options = {})
         options = options.dup
         options[:bearer_token_request] = true
         options[:grant_type] ||= "client_credentials"
         url = "https://api.twitter.com/oauth2/token"
-        headers = Twitter::Headers.new(self, :post, url, options).request_headers
+        headers = ::Twitter::Headers.new(self, :post, url, options).request_headers # steep:ignore ArgumentTypeMismatch
         response = HTTP.headers(headers).post(url, form: options)
-        response.parse["access_token"]
+        response.parse.fetch("access_token")
       end
-      alias bearer_token token
+      # @!method bearer_token
+      #   @api public
+      #   @see #token
+      alias_method :bearer_token, :token
 
-      # Allows a registered application to revoke an issued OAuth 2 Bearer Token by presenting its client credentials.
+      # Revokes an issued OAuth 2 Bearer Token
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/oauth2/invalidate_token
       # @rate_limited No
       # @authentication Required
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.invalidate_token('AAAA...')
       # @param access_token [String] The bearer token to revoke.
       # @param options [Hash] A customizable set of options.
       # @return [String] The invalidated token. token_type should be nil.
       def invalidate_token(access_token, options = {})
         options = options.dup
         options[:access_token] = access_token
-        perform_post("/oauth2/invalidate_token", options)[:access_token]
+        perform_post("/oauth2/invalidate_token", options).fetch(:access_token)
       end
 
-      # Allows a registered application to revoke an issued OAuth 2 Bearer Token by presenting its client credentials.
+      # Returns a reverse auth token for mobile applications
       #
+      # @api public
       # @see https://dev.twitter.com/rest/reference/post/oauth2/invalidate_token
       # @rate_limited No
       # @authentication Required
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @example
+      #   client.reverse_token
       # @return [String] The token string.
       def reverse_token
         options = {x_auth_mode: "reverse_auth"}
         url = "https://api.twitter.com/oauth/request_token"
-        auth_header = Twitter::Headers.new(self, :post, url, options).oauth_auth_header.to_s
+        auth_header = ::Twitter::Headers.new(self, :post, url, options).oauth_auth_header.to_s # steep:ignore ArgumentTypeMismatch
         HTTP.headers(authorization: auth_header).post(url, params: options).to_s
       end
     end