Permalink
Browse files

Add yard docs for Octokit::Users. Closes #148.

  • Loading branch information...
1 parent aaeedd0 commit e3c7fb9bdd680fdba9dbd75afcbb6fb407a43578 @joeyw joeyw committed Oct 12, 2012
Showing with 143 additions and 2 deletions.
  1. +143 −2 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 @@ def search_users(search, options={})
#
# @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 @@ def update_user(options)
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 @@ def follows?(*args)
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)
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

0 comments on commit e3c7fb9

Please sign in to comment.