Give methods more natural names

README.md

@@ -364,6 +364,24 @@ been removed:
 * `#updates_count` (use `#tweets_count`)
 * `#translator` (use `#translator?`)
 
+### More natural method names
+All create, destroy, add, and remove methods have been renamed to put the verb
+at the beginning:
+
+* `#direct_message_create` is now `#create_direct_message`
+* `#direct_message_destroy` is now `#destroy_direct_message`
+* `#list_create` is now `#create_list`
+* `#list_destroy` is now `#destroy_list`
+* `#list_remove_member` is now `#remove_list_member`
+* `#list_remove_members` is now `#remove_list_members`
+* `#list_add_member` is now `#remove_add_member`
+* `#list_add_members` is now `#remove_add_members`
+* `#lists_owned` is now `#owned_list`
+* `#place_create` is now `#create_place`
+* `#saved_search_create` is now `#create_saved_search`
+* `#saved_search_destroy` is now `#destroy_saved_search`
+* `#status_destroy` is now `#destroy_status`
+
 ### Errors
 The `Twitter::Error::ClientError` and `Twitter::Error::ServerError` class
 hierarchy has been removed. All errors now inherit directly from

lib/twitter/rest/api/direct_messages.rb

@@ -102,14 +102,15 @@ def direct_messages(*args)
         # @authentication Requires user context
         # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
         # @return [Array<Twitter::DirectMessage>] Deleted direct message.
-        # @overload direct_message_destroy(*ids)
+        # @overload destroy_direct_message(*ids)
         #   @param ids [Enumerable<Integer>] A collection of direct message IDs.
-        # @overload direct_message_destroy(*ids, options)
+        # @overload destroy_direct_message(*ids, options)
         #   @param ids [Enumerable<Integer>] A collection of direct message IDs.
         #   @param options [Hash] A customizable set of options.
-        def direct_message_destroy(*args)
+        def destroy_direct_message(*args)
           threaded_objects_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/destroy.json", args)
         end
+        deprecate_alias :direct_message_destroy, :destroy_direct_message
 
         # Sends a new direct message to the specified user from the authenticating user
         #
@@ -121,13 +122,15 @@ def direct_message_destroy(*args)
         # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
         # @param text [String] The text of your direct message, up to 140 characters.
         # @param options [Hash] A customizable set of options.
-        def direct_message_create(user, text, options={})
+        def create_direct_message(user, text, options={})
           merge_user!(options, user)
           options[:text] = text
           object_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/new.json", options)
         end
-        alias d direct_message_create
-        alias m direct_message_create
+        alias d create_direct_message
+        alias m create_direct_message
+        alias dm create_direct_message
+        deprecate_alias :direct_message_create, :create_direct_message
 
       end
     end

lib/twitter/rest/api/favorites.rb

@@ -51,9 +51,11 @@ def favorites(*args)
         def unfavorite(*args)
           threaded_objects_from_response(Twitter::Tweet, :post, "/1.1/favorites/destroy.json", args)
         end
-        alias favorite_destroy unfavorite
-        alias favourite_destroy unfavorite
+        alias destroy_favorite unfavorite
+        alias destroy_favourite unfavorite
         alias unfavourite unfavorite
+        deprecate_alias :favorite_destroy, :unfavorite
+        deprecate_alias :favourite_destroy, :unfavourite
 
         # Favorites the specified Tweets as the authenticating user
         #
@@ -80,8 +82,9 @@ def favorite(*args)
         end
         alias fav favorite
         alias fave favorite
-        alias favorite_create favorite
-        alias favourite_create favorite
+        alias favourite favorite
+        deprecate_alias :favorite_create, :favorite
+        deprecate_alias :favourite_create, :favourite
 
         # Favorites the specified Tweets as the authenticating user and raises an error if one has already been favorited
         #
@@ -107,10 +110,12 @@ def favorite!(*args)
             end
           end
         end
+        alias create_favorite! favorite!
+        alias create_favourite! favorite!
         alias fav! favorite!
         alias fave! favorite!
-        alias favorite_create! favorite!
-        alias favourite_create! favorite!
+        deprecate_alias :favorite_create!, :favorite!
+        deprecate_alias :favourite_create!, :favorite!
 
       end
     end

lib/twitter/rest/api/friends_and_followers.rb

@@ -118,7 +118,8 @@ def follow(*args)
           end
           follow!(new_friends.value - existing_friends.value, arguments.options)
         end
-        alias friendship_create follow
+        alias create_friendship follow
+        deprecate_alias :friendship_create, :follow
 
         # Allows the authenticating user to follow the specified users
         #
@@ -144,7 +145,8 @@ def follow!(*args)
             end
           end.compact
         end
-        alias friendship_create! follow!
+        alias create_friendship! follow!
+        deprecate_alias :friendship_create!, :follow!
 
         # Allows the authenticating user to unfollow the specified users
         #
@@ -161,7 +163,8 @@ def follow!(*args)
         def unfollow(*args)
           threaded_user_objects_from_response(:post, "/1.1/friendships/destroy.json", args)
         end
-        alias friendship_destroy unfollow
+        alias destroy_friendship unfollow
+        deprecate_alias :friendship_destroy, :unfollow
 
         # Allows one to enable or disable retweets and device notifications from the specified user.
         #

lib/twitter/rest/api/lists.rb

@@ -69,18 +69,19 @@ def list_timeline(*args)
         # @authentication Requires user context
         # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
         # @return [Twitter::List] The list.
-        # @overload list_remove_member(list, user_to_remove, options={})
+        # @overload remove_list_member(list, user_to_remove, options={})
         #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
         #   @param user_to_remove [Integer, String] The user id or screen name of the list member to remove.
         #   @param options [Hash] A customizable set of options.
-        # @overload list_remove_member(user, list, user_to_remove, options={})
+        # @overload remove_list_member(user, list, user_to_remove, options={})
         #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
         #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
         #   @param user_to_remove [Integer, String] The user id or screen name of the list member to remove.
         #   @param options [Hash] A customizable set of options.
-        def list_remove_member(*args)
+        def remove_list_member(*args)
           list_from_response_with_user(:post, "/1.1/lists/members/destroy.json", args)
         end
+        deprecate_alias :list_remove_member, :remove_list_member
 
         # List the lists the specified user has been added to
         #
@@ -187,18 +188,19 @@ def list_unsubscribe(*args)
         # @authentication Requires user context
         # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
         # @return [Twitter::List] The list.
-        # @overload list_add_members(list, users, options={})
+        # @overload add_list_members(list, users, options={})
         #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
         #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
         #   @param options [Hash] A customizable set of options.
-        # @overload list_add_members(user, list, users, options={})
+        # @overload add_list_members(user, list, users, options={})
         #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
         #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
         #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
         #   @param options [Hash] A customizable set of options.
-        def list_add_members(*args)
+        def add_list_members(*args)
           list_from_response_with_users(:post, "/1.1/lists/members/create_all.json", args)
         end
+        deprecate_alias :list_add_members, :add_list_members
 
         # Check if a user is a member of the specified list
         #
@@ -248,18 +250,19 @@ def list_members(*args)
         # @authentication Requires user context
         # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
         # @return [Twitter::List] The list.
-        # @overload list_add_member(list, user_to_add, options={})
+        # @overload add_list_member(list, user_to_add, options={})
         #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
         #   @param user_to_add [Integer, String] The user id or screen name to add to the list.
         #   @param options [Hash] A customizable set of options.
-        # @overload list_add_member(user, list, user_to_add, options={})
+        # @overload add_list_member(user, list, user_to_add, options={})
         #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
         #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
         #   @param user_to_add [Integer, String] The user id or screen name to add to the list.
         #   @param options [Hash] A customizable set of options.
-        def list_add_member(*args)
+        def add_list_member(*args)
           list_from_response_with_user(:post, "/1.1/lists/members/create.json", args)
         end
+        deprecate_alias :list_add_member, :add_list_member
 
         # Deletes the specified list
         #
@@ -269,16 +272,17 @@ def list_add_member(*args)
         # @authentication Requires user context
         # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
         # @return [Twitter::List] The deleted list.
-        # @overload list_destroy(list, options={})
+        # @overload destroy_list(list, options={})
         #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
         #   @param options [Hash] A customizable set of options.
-        # @overload list_destroy(user, list, options={})
+        # @overload destroy_list(user, list, options={})
         #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
         #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
         #   @param options [Hash] A customizable set of options.
-        def list_destroy(*args)
+        def destroy_list(*args)
           list_from_response(:post, "/1.1/lists/destroy.json", args)
         end
+        deprecate_alias :list_destroy, :destroy_list
 
         # Updates the specified list
         #
@@ -314,9 +318,10 @@ def list_update(*args)
         # @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 list_create(name, options={})
+        def create_list(name, options={})
           object_from_response(Twitter::List, :post, "/1.1/lists/create.json", options.merge(:name => name))
         end
+        deprecate_alias :list_create, :create_list
 
         # Show the specified list
         #
@@ -362,18 +367,19 @@ def subscriptions(*args)
         # @authentication Requires user context
         # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
         # @return [Twitter::List] The list.
-        # @overload list_remove_members(list, users, options={})
+        # @overload remove_list_members(list, users, options={})
         #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
         #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
         #   @param options [Hash] A customizable set of options.
-        # @overload list_remove_members(user, list, users, options={})
+        # @overload remove_list_members(user, list, users, options={})
         #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
         #   @param list [Integer, String, Twitter::List] A Twitter list ID, slug, URI, or object.
         #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
         #   @param options [Hash] A customizable set of options.
-        def list_remove_members(*args)
+        def remove_list_members(*args)
           list_from_response_with_users(:post, "/1.1/lists/members/destroy_all.json", args)
         end
+        deprecate_alias :list_remove_members, :remove_list_members
 
         # Returns the lists owned by the specified Twitter user
         #
@@ -382,17 +388,18 @@ def list_remove_members(*args)
         # @authentication Requires user context
         # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
         # @return [Array<Twitter::List>]
-        # @overload lists_owned(options={})
+        # @overload owned_lists(options={})
         #   @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.
-        # @overload lists_owned(user, options={})
+        # @overload owned_lists(user, options={})
         #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
         #   @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 lists_owned(*args)
+        def owned_lists(*args)
           cursor_from_response_with_user(:lists, Twitter::List, :get, "/1.1/lists/ownerships.json", args)
         end
-        alias lists_ownerships lists_owned
+        deprecate_alias :lists_ownerships, :owned_lists
+        deprecate_alias :lists_owned, :owned_lists
 
       private
 

lib/twitter/rest/api/places_and_geo.rb

@@ -94,9 +94,10 @@ def similar_places(options={})
         # @option options [Float] :long The longitude to search around. The valid range for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.
         # @option options [String] :"attribute:street_address" This option searches for places which have this given street address. There are other well-known and application-specific attributes available. Custom attributes are also permitted.
         # @return [Twitter::Place] The created place.
-        def place_create(options={})
+        def create_place(options={})
           object_from_response(Twitter::Place, :post, "/1.1/geo/place.json", options)
         end
+        deprecate_alias :place_create, :create_place
 
       end
     end

lib/twitter/rest/api/saved_searches.rb

@@ -61,9 +61,10 @@ def saved_search(id, options={})
         # @return [Twitter::SavedSearch] The created saved search.
         # @param query [String] The query of the search the user would like to save.
         # @param options [Hash] A customizable set of options.
-        def saved_search_create(query, options={})
+        def create_saved_search(query, options={})
           object_from_response(Twitter::SavedSearch, :post, "/1.1/saved_searches/create.json", options.merge(:query => query))
         end
+        deprecate_alias :saved_search_create, :create_saved_search
 
         # Destroys saved searches for the authenticated user
         #
@@ -73,17 +74,18 @@ def saved_search_create(query, options={})
         # @authentication Requires user context
         # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
         # @return [Array<Twitter::SavedSearch>] The deleted saved searches.
-        # @overload saved_search_destroy(*ids)
+        # @overload destroy_saved_search(*ids)
         #   @param ids [Enumerable<Integer>] A collection of saved search IDs.
-        # @overload saved_search_destroy(*ids, options)
+        # @overload destroy_saved_search(*ids, options)
         #   @param ids [Enumerable<Integer>] A collection of saved search IDs.
         #   @param options [Hash] A customizable set of options.
-        def saved_search_destroy(*args)
+        def destroy_saved_search(*args)
           arguments = Twitter::Arguments.new(args)
           arguments.flatten.threaded_map do |id|
             object_from_response(Twitter::SavedSearch, :post, "/1.1/saved_searches/destroy/#{id}.json", arguments.options)
           end
         end
+        deprecate_alias :saved_search_destroy, :destroy_saved_search
 
       end
     end

lib/twitter/rest/api/tweets.rb

@@ -87,16 +87,18 @@ def statuses(*args)
         # @authentication Requires user context
         # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
         # @return [Array<Twitter::Tweet>] The deleted Tweets.
-        # @overload status_destroy(*tweets)
+        # @overload destroy_status(*tweets)
         #   @param tweets [Enumerable<Integer, String, URI, Twitter::Tweet>] A collection of Tweet IDs, URIs, or objects.
-        # @overload status_destroy(*tweets, options)
+        # @overload destroy_status(*tweets, options)
         #   @param tweets [Enumerable<Integer, String, URI, Twitter::Tweet>] A collection of Tweet IDs, URIs, or objects.
         #   @param options [Hash] A customizable set of options.
         #   @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.
-        def status_destroy(*args)
+        def destroy_status(*args)
           threaded_tweets_from_response(:post, "/1.1/statuses/destroy", args)
         end
-        alias tweet_destroy status_destroy
+        alias destroy_tweet destroy_status
+        deprecate_alias :status_destroy, :destroy_status
+        deprecate_alias :tweet_destroy, :destroy_status
 
         # Updates the authenticating user's status
         #

lib/twitter/rest/api/users.rb

@@ -337,6 +337,7 @@ def contributors(*args)
         def remove_profile_banner(options={})
           post("/1.1/account/remove_profile_banner.json", options)[:body]
         end
+        deprecate_alias :profile_banner_remove, :remove_profile_banner
 
         # Updates the authenticating user's profile banner image
         #

lib/twitter/rest/api/utils.rb

@@ -7,10 +7,26 @@ module Twitter
   module REST
     module API
       module Utils
-
         DEFAULT_CURSOR = -1
         URI_SUBSTRING = "://"
 
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+
+          private
+
+          def deprecate_alias(new_name, old_name)
+            define_method(new_name) do |*args, &block|
+              warn "#{Kernel.caller.first}: [DEPRECATION] ##{new_name} it deprecated. Use ##{old_name} instead."
+              send(old_name, *args, &block)
+            end
+          end
+
+        end
+
       private
 
         # Take a URI string or Twitter::Identity object and return its ID