octokit 1.17.1 → 1.18.0

data/lib/octokit/client/pulls.rb

@@ -68,6 +68,31 @@ module Octokit
         post("repos/#{Repository.new(repo)}/pulls", options.merge(pull))
       end
 
+      # Update a pull request
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param id [Integer] Id of pull request to update.
+      # @param title [String] Title for the pull request.
+      # @param body [String] Body content for pull request. Supports GFM.
+      # @param state [String] State of the pull request. `open` or `closed`.
+      # @return [Hashie::Mash] Hash representing updated pull request.
+      # @see http://developer.github.com/v3/pulls/#update-a-pull-request
+      # @example
+      #   @client.update_pull_request('pengwynn/octokit', 67, 'new title', 'updated body', 'closed')
+      # @example Passing nil for optional attributes to update specific attributes.
+      #   @client.update_pull_request('pengwynn/octokit', 67, nil, nil, 'open')
+      # @example Empty body by passing empty string
+      #   @client.update_pull_request('pengwynn/octokit', 67, nil, '')
+      def update_pull_request(repo, id, title=nil, body=nil, state=nil, options={})
+        options.merge!({
+          :title => title,
+          :body => body,
+          :state => state
+        })
+        options.reject! { |_, value| value.nil? }
+        post("repos/#{Repository.new repo}/pulls/#{id}", options, 3)
+      end
+
 
       # List commits on a pull request
       #

data/lib/octokit/client/repositories.rb

@@ -186,73 +186,254 @@ module Octokit
         update_repository repo, options.merge({ :private => false })
       end
 
+      # Get deploy keys on a repo
+      #
+      # Requires authenticated client.
+      # 
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @return [Array<Hashie::Mash>] Array of hashes representing deploy keys.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/keys/#get
+      # @example
+      #   @client.deploy_keys('pengwynn/octokit')
+      # @example
+      #   @client.list_deploy_keys('pengwynn/octokit')
       def deploy_keys(repo, options={})
         get "repos/#{Repository.new repo}/keys", options, 3
       end
       alias :list_deploy_keys :deploy_keys
 
+      # Add deploy key to a repo
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param title [String] Title reference for the deploy key.
+      # @param key [String] Public key.
+      # @return [Hashie::Mash] Hash representing newly added key.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/keys/#create
+      # @example
+      #    @client.add_deploy_key('pengwynn/octokit', 'Staging server', 'ssh-rsa AAA...')
       def add_deploy_key(repo, title, key, options={})
         post "repos/#{Repository.new repo}/keys", options.merge(:title => title, :key => key), 3
       end
 
+      # Remove deploy key from a repo
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param id [Integer] Id of the deploy key to remove.
+      # @return [Boolean] True if key removed, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/keys/#delete
+      # @example
+      #   @client.remove_deploy_key('pengwynn/octokit', 100000)
       def remove_deploy_key(repo, id, options={})
         delete "repos/#{Repository.new repo}/keys/#{id}", options, 3
       end
 
+      # List collaborators
+      #
+      # Requires authenticated client for private repos.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @return [Array<Hashie::Mash>] Array of hashes representing collaborating users.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/collaborators/#list
+      # @example
+      #   Octokit.collaborators('pengwynn/octokit')
+      # @example
+      #   Octokit.collabs('pengwynn/octokit')
+      # @example
+      #   @client.collabs('pengwynn/octokit')
       def collaborators(repo, options={})
         get "repos/#{Repository.new repo}/collaborators", options, 3
       end
       alias :collabs :collaborators
 
+      # Add collaborator to repo
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param collaborator [String] Collaborator GitHub username to add.
+      # @return [Boolean] True if collaborator added, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/collaborators/#add-collaborator
+      # @example
+      #   @client.add_collaborator('pengwynn/octokit', 'holman')
+      # @example
+      #   @client.add_collab('pengwynn/octokit', 'holman')
       def add_collaborator(repo, collaborator, options={})
         put "repos/#{Repository.new repo}/collaborators/#{collaborator}", options, 3
       end
       alias :add_collab :add_collaborator
 
+      # Remove collaborator from repo.
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param collaborator [String] Collaborator GitHub username to remove.
+      # @return [Boolean] True if collaborator removed, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/collaborators/#remove-collaborator
+      # @example
+      #   @client.remove_collaborator('pengwynn/octokit', 'holman')
+      # @example
+      #   @client.remove_collab('pengwynn/octokit', 'holman')
       def remove_collaborator(repo, collaborator, options={})
         delete "repos/#{Repository.new repo}/collaborators/#{collaborator}", options, 3
       end
       alias :remove_collab :remove_collaborator
 
+      # List teams for a repo
+      #
+      # Requires authenticated client that is an owner or collaborator of the repo.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @return [Array<Hashie::Mash>] Array of hashes representing teams.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/#list-teams
+      # @example
+      #   @client.repository_teams('octokit/pengwynn')
+      # @example
+      #   @client.repo_teams('octokit/pengwynn')
+      # @example
+      #   @client.teams('octokit/pengwynn')
       def repository_teams(repo, options={})
         get "repos/#{Repository.new repo}/teams", options, 3
       end
       alias :repo_teams :repository_teams
       alias :teams :repository_teams
 
+      # List contributors to a repo
+      #
+      # Requires authenticated client for private repos.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param anon [Boolean] Set true to include annonymous contributors.
+      # @return [Array<Hashie::Mash>] Array of hashes representing users.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/#list-contributors
+      # @example
+      #   Octokit.contributors('pengwynn/octokit', true)
+      # @example
+      #   Octokit.contribs('pengwynn/octokit')
+      # @example
+      #   @client.contribs('pengwynn/octokit') 
       def contributors(repo, anon=false, options={})
         get "repos/#{Repository.new repo}/contributors", options.merge(:anon => anon), 3
       end
       alias :contribs :contributors
 
+      # List stargazers of a repo
+      #
+      # Requires authenticated client for private repos.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @return [Array<Hashie::Mash>] Array of hashes representing users.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/starring/#list-stargazers
+      # @example
+      #   Octokit.stargazers('pengwynn/octokit')
+      # @example
+      #   @client.stargazers('pengwynn/octokit')
       def stargazers(repo, options={})
         get "repos/#{Repository.new repo}/stargazers", options, 3
       end
 
+      # @deprecated Use #stargazers instead
+      #
+      # List watchers of repo.  
+      #
+      # Requires authenticated client for private repos.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @return [Array<Hashie::Mash>] Array of hashes representing users.
+      # @see Octokit::Client::Repositories#stargazers
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/watching/#list-watchers
+      # @example
+      #   Octokit.watchers('pengwynn/octokit')
+      # @example
+      #   @client.watchers('pengwynn/octokit')
       def watchers(repo, options={})
         get "repos/#{Repository.new repo}/watchers", options, 3
       end
 
+      # List forks
+      #
+      # Requires authenticated client for private repos.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @return [Array<Hashie::Mash>] Array of hashes representing repos.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/forks/#list-forks
+      # @example
+      #   Octokit.forks('pengwynn/octokit')
+      # @example
+      #   Octokit.network('pengwynn/octokit')
+      # @example
+      #   @client.forks('pengwynn/octokit')
       def forks(repo, options={})
         get "repos/#{Repository.new repo}/forks", options, 3
       end
       alias :network :forks
 
+      # List languages of code in the repo.
+      #
+      # Requires authenticated client for private repos.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @return [Array<Hashie::Mash>] Array of Hashes representing languages.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/#list-languages
+      # @example
+      #   Octokit.langauges('pengwynn/octokit')
+      # @example
+      #   @client.languages('pengwynn/octokit')
       def languages(repo, options={})
         get "repos/#{Repository.new repo}/languages", options, 3
       end
 
+      # List tags
+      #
+      # Requires authenticated client for private repos.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @return [Array<Hashie::Mash>] Array of hashes representing tags.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/#list-tags
+      # @example
+      #   Octokit.tags('pengwynn/octokit')
+      # @example
+      #   @client.tags('pengwynn/octokit')
       def tags(repo, options={})
         get "repos/#{Repository.new repo}/tags", options, 3
       end
 
+      # List branches
+      #
+      # Requires authenticated client for private repos.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @return [Array<Hashie::Mash>] Array of hashes representing branches.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/#list-branches
+      # @example
+      #   Octokit.branches('pengwynn/octokit')
+      # @example
+      #   @client.branches('pengwynn/octokit')
       def branches(repo, options={})
         get "repos/#{Repository.new repo}/branches", options, 3
       end
 
       # Get a single branch from a repository
       #
-      # @param repo [String, Repository, Hash] A GitHub repository
+      # @param repo [String, Hash, Repository] A GitHub repository.
       # @param branch [String] Branch name
       # @return [Branch] The branch requested, if it exists
       # @see http://developer.github.com/v3/repos/#get-branch
@@ -263,28 +444,139 @@ module Octokit
       end
       alias :get_branch :branch
 
+      # List repo hooks
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @return [Array<Hashie::Mash>] Array of hashes representing hooks.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/hooks/#list
+      # @example
+      #   @client.hooks('pengwynn/octokit')
       def hooks(repo, options={})
         get "repos/#{Repository.new repo}/hooks", options, 3
       end
 
+      # Get single hook
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param id [Integer] Id of the hook to get.
+      # @return [Hashie::Mash] Hash representing hook.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/hooks/#get-single-hook
+      # @example
+      #   @client.hook('pengwynn/octokit', 100000)
       def hook(repo, id, options={})
         get "repos/#{Repository.new repo}/hooks/#{id}", options, 3
       end
 
+      # Create a hook
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param name [String] The name of the service that is being called. See
+      #   {https://api.github.com/hooks Hooks} for the possible names.
+      # @param config [Hash] A Hash containing key/value pairs to provide
+      #   settings for this hook. These settings vary between the services and
+      #   are defined in the {https://github.com/github/github-services github-services} repo.
+      # @option options [Array<String>] :events ('["push"]') Determines what
+      #   events the hook is triggered for.
+      # @option options [Boolean] :active Determines whether the hook is
+      #   actually triggered on pushes.
+      # @see Octokit::Client
+      # @see https://api.github.com/hooks
+      # @see https://github.com/github/github-services
+      # @see http://developer.github.com/v3/repos/hooks/#create-a-hook
+      # @example
+      #   @client.create_hook(
+      #     'pengwynn/octokit',
+      #     'web',
+      #     {
+      #       :url => 'http://something.com/webhook',
+      #       :content_type => 'json'
+      #     },
+      #     {
+      #       :events => ['push', 'pull_request'],
+      #       :active => true
+      #     }
+      #   )
       def create_hook(repo, name, config, options={})
         options = {:name => name, :config => config, :events => ["push"], :active => true}.merge(options)
         post "repos/#{Repository.new repo}/hooks", options, 3
       end
 
+      # Edit a hook
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param id [Integer] Id of the hook being updated.
+      # @param name [String] The name of the service that is being called. See
+      #   {https://api.github.com/hooks Hooks} for the possible names.
+      # @param config [Hash] A Hash containing key/value pairs to provide
+      #   settings for this hook. These settings vary between the services and
+      #   are defined in the {https://github.com/github/github-services github-services} repo.
+      # @option options [Array<String>] :events ('["push"]') Determines what 
+      #   events the hook is triggered for.
+      # @option options [Array<String>] :add_events Determines a list of events
+      #   to be added to the list of events that the Hook triggers for.
+      # @option options [Array<String>] :remove_events Determines a list of events
+      #   to be removed from the list of events that the Hook triggers for.
+      # @option options [Boolean] :active Determines whether the hook is
+      #   actually triggered on pushes.
+      # @see Octokit::Client
+      # @see https://api.github.com/hooks
+      # @see https://github.com/github/github-services
+      # @see http://developer.github.com/v3/repos/hooks/#edit-a-hook
+      # @example
+      #   @client.edit_hook(
+      #     'pengwynn/octokit',
+      #     'web',
+      #     {
+      #       :url => 'http://something.com/webhook',
+      #       :content_type => 'json'
+      #     },
+      #     {
+      #       :add_events => ['status'],
+      #       :remove_events => ['pull_request'],
+      #       :active => true
+      #     }
+      #   )
       def edit_hook(repo, id, name, config, options={})
         options = {:name => name, :config => config, :events => ["push"], :active => true}.merge(options)
         patch "repos/#{Repository.new repo}/hooks/#{id}", options, 3
       end
 
+      # Delete hook
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param id [Integer] Id of the hook to remove.
+      # @return [Boolean] True if hook removed, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/hooks/#delete-a-hook
+      # @example
+      #   @client.remove_hook('pengwynn/octokit', 1000000)
       def remove_hook(repo, id, options={})
         delete "repos/#{Repository.new repo}/hooks/#{id}", options, 3
       end
 
+      # Test hook
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param id [Integer] Id of the hook to test.
+      # @return [nil]
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/hooks/#test-a-hook
+      # @example
+      #   @client.test_hook('pengwynn/octokit', 1000000)
       def test_hook(repo, id, options={})
         post "repos/#{Repository.new repo}/hooks/#{id}/test", options, 3
       end
@@ -302,6 +594,20 @@ module Octokit
       end
       alias :repo_issue_events :repository_issue_events
 
+      # List users available for assigning to issues.
+      #
+      # Requires authenticated client for private repos.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @returns [Array<Hashie::Mash>] Array of hashes representing users.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/issues/assignees/#list-assignees
+      # @example
+      #   Octokit.repository_assignees('pengwynn/octokit')
+      # @example
+      #   Octokit.repo_assignees('pengwynn/octokit')
+      # @example
+      #   @client.repository_assignees('pengwynn/octokit')
       def repository_assignees(repo, options={})
         get "repos/#{Repository.new repo}/assignees", options, 3
       end

data/lib/octokit/client/users.rb

@@ -1,7 +1,18 @@
 module Octokit
   class Client
+    #@todo Add support for getting a single public key by id.
+    #  http://developer.github.com/v3/users/keys/#get-a-single-public-key
+    #@todo Add support for updating a public key.
+    #  http://developer.github.com/v3/users/keys/#update-a-public-key
     module Users
 
+      # Search for user.
+      #
+      # @param search [String] User to search for.
+      # @return [Array<Hashie::Mash>] Array of hashes representing users.
+      # @see http://developer.github.com/v3/search/#search-users
+      # @example
+      #   Octokit.search_users('pengwynn')
       def search_users(search, options={})
         get("legacy/user/search/#{search}", options, 3)['users']
       end
@@ -10,6 +21,7 @@ module Octokit
       #
       # @param user [String] A GitHub user name.
       # @return [Hashie::Mash]
+      # @see http://developer.github.com/v3/users/#get-a-single-user
       # @example
       #   Octokit.user("sferik")
       def user(user=nil)
@@ -37,14 +49,38 @@ module Octokit
         patch("user", options, 3)
       end
 
+      # Get a user's followers.
+      #
+      # @param user [String] Username of the user whose list of followers you are getting.
+      # @return [Array<Hashie::Mash>] Array of hashes representing users followers.
+      # @see http://developer.github.com/v3/users/followers/#list-followers-of-a-user
+      # @example
+      #   Octokit.followers('pengwynn')
       def followers(user=login, options={})
         get("users/#{user}/followers", options, 3)
       end
 
+      # Get list of users a user is following.
+      #
+      # @param user [String] Username of the user who you are getting the list of the people they follow.
+      # @return [Array<Hashie::Mash>] Array of hashes representing users a user is following.
+      # @see  http://developer.github.com/v3/users/followers/#list-users-following-another-user
+      # @example
+      #   Octokit.following('pengwynn')
       def following(user=login, options={})
         get("users/#{user}/following", options, 3)
       end
 
+      # Check if you are following a user.
+      #
+      # Requries an authenticated client.
+      # 
+      # @param user [String] Username of the user that you want to check if you are following.
+      # @return [Boolean] True if you are following the user, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/users/followers/#check-if-you-are-following-a-user
+      # @example
+      #   @client.follows?('pengwynn')
       def follows?(*args)
         target = args.pop
         user = args.first
@@ -55,50 +91,155 @@ module Octokit
         false
       end
 
+      # Follow a user.
+      #
+      # Requires authenticatied client.
+      #
+      # @param user [String] Username of the user to follow.
+      # @return [Boolean] True if follow was successful, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/users/followers/#follow-a-user
+      # @example
+      #   @client.follow('holman')
       def follow(user, options={})
         put("user/following/#{user}", options, 3, true, raw=true).status == 204
       end
 
+      # Unfollow a user.
+      #
+      # Requires authenticated client.
+      #
+      # @param user [String] Username of the user to unfollow.
+      # @return [Boolean] True if unfollow was successful, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/users/followers/#unfollow-a-user
+      # @example
+      #   @client.unfollow('holman')
       def unfollow(user, options={})
         delete("user/following/#{user}", options, 3, true, raw=true).status == 204
       end
 
+      # Get list of repos starred by a user.
+      #
+      # @param user [String] Username of the user to get the list of their starred repositories.
+      # @return [Array<Hashie::Mash>] Array of hashes representing repositories starred by user.
+      # @see http://developer.github.com/v3/repos/starring/#list-repositories-being-starred
+      # @example
+      #   Octokit.starred('pengwynn')
       def starred(user=login, options={})
         get("users/#{user}/starred", options, 3)
       end
 
+      # Check if you are starring a repo.
+      #
+      # Requires authenticated client.
+      #
+      # @param user [String] Username of repository owner.
+      # @param repo [String] Name of the repository.
+      # @return [Boolean] True if you are following the repo, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/starring/#check-if-you-are-starring-a-repository
+      # @example
+      #   @client.starred?('pengwynn', 'octokit')
       def starred?(user, repo, options={})
         get("user/starred/#{user}/#{repo}", options, 3, true, raw=true).status == 204
       rescue Octokit::NotFound
         false
       end
 
+      # Get list of repos watched by a user.
+      # 
+      # Legacy, using github.beta media type. Use `Users#starred` instead.
+      #
+      # @param user [String] Username of the user to get the list of repositories they are watching.
+      # @return [Array<Hashie::Mash>] Array of hashes representing repositories watched by user.
+      # @see Users#starred
+      # @see http://developer.github.com/v3/repos/starring/#list-stargazers
+      # @example
+      #   Octokit.watched('pengwynn')
       def watched(user=login, options={})
         get("users/#{user}/watched", options, 3)
       end
 
-      # Not yet supported: get a single key, update an existing key
-
+      # Get list of public keys for user.
+      #
+      # Requires authenticated client.
+      #
+      # @return [Array<Hashie::Mash>] Array of hashes representing public keys.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/users/keys/#list-public-keys-for-a-user
+      # @example
+      #   @client.keys
       def keys(options={})
         get("user/keys", options, 3)
       end
 
+      # Add public key to user account.
+      #
+      # Requires authenticated client.
+      #
+      # @param title [String] Title to give reference to the public key.
+      # @param key [String] Public key.
+      # @return [Hashie::Mash] Hash representing the newly added public key.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/users/keys/#create-a-public-key
+      # @example
+      #   @client.add_key('Personal projects key', 'ssh-rsa AAA...')
       def add_key(title, key, options={})
         post("user/keys", options.merge({:title => title, :key => key}), 3)
       end
 
+      # Remove a public key from user account.
+      #
+      # Requires authenticated client.
+      #
+      # @param id [String] Id of the public key to remove.
+      # @return [Boolean] True if removal was successful, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/users/keys/#delete-a-public-key
+      # @example
+      #   @client.remove_key(1)
       def remove_key(id, options={})
-        delete("user/keys/#{id}", options, 3, true, raw=true)
+        delete("user/keys/#{id}", options, 3, true, raw=true).status == 204
       end
 
+      # List email addresses for a user.
+      #
+      # Requires authenticated client.
+      #
+      # @return [Array<String>] Array of email addresses.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/users/emails/#list-email-addresses-for-a-user
+      # @example
+      #   @client.emails
       def emails(options={})
         get("user/emails", options, 3)
       end
 
+      # Add email address to user.
+      #
+      # Requires authenticated client.
+      #
+      # @param email [String] Email address to add to the user.
+      # @return [Array<String>] Array of all email addresses of the user.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/users/emails/#add-email-addresses
+      # @example
+      #   @client.add_email('new_email@user.com')
       def add_email(email, options={})
         post("user/emails", options.merge({:email => email}), 3)
       end
 
+      # Remove email from user.
+      #
+      # Requires authenticated client.
+      #
+      # @param email [String] Email address to remove.
+      # @return [Array<String>] Array of all email addresses of the user.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/users/emails/#delete-email-addresses
+      # @example
+      #   @client.remove_email('old_email@user.com')
       def remove_email(email, options={})
         delete("user/emails", options.merge({:email => email}), 3, true, raw=true).status == 204
       end