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

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