Permalink
Browse files

Added yardoc documentation

  • Loading branch information...
1 parent 2db0dff commit 6b1f353bc3077dbdfe695bd77f69354a51996446 @seejohnrun committed Oct 6, 2011
View
@@ -3,3 +3,5 @@
*.swp
Gemfile.lock
.bundle
+yardoc
+.yardoc
View
@@ -0,0 +1,9 @@
+--readme README.md
+--title 'GooglePlus API Documentation'
+--charset utf-8
+--protected
+--no-private
+--readme README.md
+--hide-void-return
+--markup markdown
+--output-dir ./yardoc
View
@@ -6,120 +6,96 @@ This is a Ruby client library for the [Google+ API](http://developers.google.com
## Installation
-``` bash
-gem install google_plus
-```
+ gem install google_plus
## Authentication
To make calls to the Google+ API, you have to either authenticate via [OAuth](http://oauth.net/) or provide an API key (which you can get from the Google [APIs Console](https://code.google.com/apis/console#access). To set your API key and get started, use:
-``` ruby
-GooglePlus.api_key = 'your key'
-```
+ GooglePlus.api_key = 'your key'
That key will then be used on all of your requests.
If you want to change it for an individual request, you can use a param, like:
-``` ruby
-person = GooglePlus::Person.get(123, :key => 'other_key')
-```
+ person = GooglePlus::Person.get(123, :key => 'other_key')
## People
Getting information about a person is easy, given that you have their Google+ ID:
-``` ruby
-person = GooglePlus::Person.get(123)
-```
+ person = GooglePlus::Person.get(123)
Accessing attributes of a `GooglePlus::Person` object is straightforward, and to keep things nice, all attributes are converted to snake case (so `person.displayName` becomes `person.display_name`).
-``` ruby
-person = GooglePlus::Person.get(123)
-person.display_name
-person.photos.each do |photo|
- photo.value
-end
-```
+ person = GooglePlus::Person.get(123)
+ person.display_name
+ person.photos.each do |photo|
+ photo.value
+ end
You can read more about the fields available for a `Person` in the [Person documentation](http://developers.google.com/+/api/latest/people), or you can use the `attributes` method to get them back as a Hash.
## Activities
Exactly the same as people, you can get activities by ID:
-``` ruby
-activity = GooglePlus::Activity.get(123)
-```
+ activity = GooglePlus::Activity.get(123)
And once you have an activity, you can move back to its person using `#person`.
-## People do Things
+### People do Things
Lastly, you can get a list of activities for a person, which is returned as a `GooglePlus::Cursor`. You use it like:
-``` ruby
-person = GooglePlus::Person.new(123)
-cursor = person.list_activities
-while cursor.next_page
- cursor.items.count # a batch of activities
-end
-```
+ person = GooglePlus::Person.new(123)
+ cursor = person.list_activities
+ while cursor.next_page
+ cursor.items.count # a batch of activities
+ end
Or if you just want one page, you can have it:
-``` ruby
-person = GooglePlus::Person.new(123)
-activites = person.activities_list.items
-```
+ person = GooglePlus::Person.new(123)
+ activites = person.activities_list.items
You can also set the cursor size at any time using any of these variations:
-``` ruby
-# on the cursor
-cursor = person.activities_list(:max_results => 10)
-# or on the page
-cursor.next_page(:max_results => 5)
-```
+ # on the cursor
+ cursor = person.activities_list(:max_results => 10)
+ # or on the page
+ cursor.next_page(:max_results => 5)
-## Plusoners and Resharers
+### Plusoners and Resharers
You can call `plusoners` and `resharers` on a `GooglePlus::Activity` to get a cursor or people that plus one'd or reshared an activity.
## Comments
You can get comments for an acitivty, using its ID:
-``` ruby
-comment = GooglePlus::Comment.get(123)
-```
+ comment = GooglePlus::Comment.get(123)
Accessing attributes of a `GooglePlus::Comment` object is straightforward, (see: accessing attributes of a `GooglePlus::Person`). You can find the fields available in the [Comment documentation](https://developers.google.com/+/api/latest/comments/list).
Getting comments for an activity is done just like getting activities for a person:
-``` ruby
-activity = GooglePlus::Activity.get(123)
-cursor = activity.list_comments
-while cursor.next_page
- cursor.items.count # a bunch of comments
-end
-```
+ activity = GooglePlus::Activity.get(123)
+ cursor = activity.list_comments
+ while cursor.next_page
+ cursor.items.count # a bunch of comments
+ end
## Searching
You can search for [people](https://developers.google.com/+/api/latest/people/search) or [activities](https://developers.google.com/+/api/latest/activities/search) using the respective `search` methods, which also yield `GooglePlus::Cursor` objects. Here's an example:
-``` ruby
-search = GooglePlus::Person.search('john crepezzi')
-while search.next_page
- search.each do |p|
- puts p.display_name
- end
-end
-```
+ search = GooglePlus::Person.search('john crepezzi')
+ while search.next_page
+ search.each do |p|
+ puts p.display_name
+ end
+ end
## Setting options
View
@@ -7,7 +7,7 @@ spec = Gem::Specification.new do |s|
s.email = 'john.crepezzi@gmail.com'
s.add_development_dependency 'rspec', '~> 2.6.0'
s.add_dependency 'rest-client', '~> 1.6.1'
- s.files = Dir['lib/**/*.rb']
+ s.files = Dir['lib/**/*.rb'] + ['README.md']
s.has_rdoc = true
s.homepage = 'http://github.com/seejohnrun/google_plus'
s.platform = Gem::Platform::RUBY
View
@@ -2,6 +2,7 @@
require File.dirname(__FILE__) + '/google_plus/resource'
require File.dirname(__FILE__) + '/google_plus/cursor'
+# GooglePlus is a ruby library for accessing the
module GooglePlus
autoload :Activity, File.dirname(__FILE__) + '/google_plus/activity'
@@ -12,9 +13,9 @@ class << self
attr_accessor :api_key, :access_token
end
- # Return whether or not the we have an API
- # For historic purposes - since this client existed before there
- # was a GooglePlus API
+ # Return whether or not there is a Google+ API
+ # For historic purposes - since this client existed before there was a GooglePlus API
+ # @return [Boolean] whether or not there is an API
def self.has_api?
true
end
@@ -8,51 +8,80 @@ class Activity
extend GooglePlus::Resource
include GooglePlus::Entity
+ # Get an activity by ID
+ # @param [String] activity_id The id of the activity to look up
+ # @option params [Symbol] :key A different API key to use for this request
+ # @option params [Symbol] :user_ip The IP of the user on who's behalf this request is made
+ # @return [GooglePlus::Activity] an activity object for the activity, if it
+ # is found - otherwise, return nil
def self.get(activity_id, params = {})
data = make_request(:get, "activities/#{activity_id}", params)
Activity.new(JSON.parse(data)) if data
end
+ # Search for an activity
+ # @param [String] query The query string to search for
+ # @option params [Symbol] :key A different API key to use for this request
+ # @option params [Symbol] :user_ip The IP of the user on who's behalf this request is made
+ # @return [GooglePlus::Cursor] a cursor that will paginate through the results
+ # for the activity search
def self.search(query, params = {})
params[:query] = URI.escape(query)
params[:orderBy] = params.delete(:order_by) if params.has_key?(:order_by)
resource = 'activities'
GooglePlus::Cursor.new(self, :get, resource, params)
end
- def self.for_person(user_id, params = {})
+ # Get a list of activities from this person
+ # @param [String] user_id The ID of the user to look up activities for
+ # @option params [Symbol] :collection What collection to pull activities for
+ # defaults to :public
+ # @option params [Symbol] :key A different API key to use for this request
+ # @option params [Symbol] :user_ip The IP of the user on who's behalf this request is made
+ # @return [GooglePlus::Cursor] a cursor that will paginate through the results
+ # for the activity list
+ def self.for_person(user_id, params = {})
collection = params[:collection] || :public
resource = "people/#{user_id}/activities/#{collection}"
GooglePlus::Cursor.new(self, :get, resource, params)
end
- # get the comments for this activity
+ # Get the list of comments for an activity
+ # @return [GooglePlus::Cursor] a cursor for paginating through the comments on this activity
def list_comments
GooglePlus::Comment.for_activity(id)
end
# get the actor of this activity
+ # @return [GooglePlus::Person] the actor for this activity
def person
@person ||= GooglePlus::Person.get(actor.id)
end
- # list the people of a certain action on this activity
- # options available at https://developers.google.com/+/api/latest/people/listByActivity
- def list_people(collection, params = {})
+ # List the people of a certain type of action on this activity
+ # @param [Symbol] collection The collection to look up (ie: :plusoners, :resharers)
+ # @return [GooglePlus::Cursor] a cursor for the list of people associated with this activity
+ def list_people(collection)
resource = "activities/#{id}/people/#{collection}"
- GooglePlus::Cursor.new(GooglePlus::Person, :get, resource, params)
+ GooglePlus::Cursor.new(GooglePlus::Person, :get, resource)
end
- # get a cursor for the plusoners of this activity
- def plusoners(params = {})
+ # List the people that plusone'd this activity
+ # @return [GooglePlus::Cursor] a cursor for the list of people that plusone'd this activity
+ def plusoners
list_people(:plusoners)
end
- # get a cursor for the resharers of this activity
- def resharers(params = {})
+ # List the people that reshared this activity
+ # @return [GooglePlus::Cursor] a cursor for the list of people that reshared this activity
+ def resharers
list_people(:resharers)
end
+ # Load a new instance from an attributes hash
+ # Useful if you have the underlying response data for an object - Generally, what you
+ # want is #get though
+ # @return [GooglePlus::Activity] An activity constructed from the attributes hash
def initialize(hash)
load_hash(hash)
end
View
@@ -8,16 +8,31 @@ class Comment
extend GooglePlus::Resource
include GooglePlus::Entity
+ # Get a comment by id
+ # @param [String] comment_id The id of the comment to look up
+ # @option params [Symbol] :key A different API key to use for this request
+ # @option params [Symbol] :user_ip The IP of the user on who's behalf this request is made
+ # @return [GooglePlus::Comment] a comment object representing the comment we're looking up,
+ # if it is found - otherwise, return nil
def self.get(comment_id, params = {})
data = make_request(:get, "comments/#{comment_id}", params)
Comment.new(JSON.parse(data)) if data
end
+ # Get a cursor of comments for an activity
+ # @param [String] activity_id The id of the activity to look up comments for
+ # @option params [Symbol] :key A different API key to use for this request
+ # @option params [Symbol] :user_ip The IP of the user on who's behalf this request is made
+ # @return [GooglePlus::Cursor] a cursor for listing the comments for this activity
def self.for_activity(activity_id, params = {})
resource = "activities/#{activity_id}/comments"
GooglePlus::Cursor.new(self, :get, resource, params)
end
+ # Load a new instance from an attributes hash.
+ # Useful if you have the underlying response data for an object - Generally, what you
+ # want is #get though
+ # @return [GooglePlus::Comment] A comment constructed from the attributes hash
def initialize(hash)
load_hash(hash)
end
@@ -19,7 +19,7 @@ def next_page(params = {})
@items = load_page(params)
end
- def initialize(klass, method, resource, params)
+ def initialize(klass, method, resource, params = {})
@first_page_loaded = false
@resource_klass = klass
@method = method
@@ -2,10 +2,14 @@ module GooglePlus
class ConnectionError < Exception
+ # Initialize a new ConnectionError
+ # @param [Exception] e The exception that occurred
def initialize(e)
@exception = e
end
+ # Get the message for this error
+ # @return [String] a message representing this error
def message
@exception.message
end
View
@@ -8,22 +8,38 @@ class Person
extend GooglePlus::Resource
include GooglePlus::Entity
+ # Get a person by id
+ # @param [String] user_id the id of the user to look up
+ # @option params [Symbol] :key A different API key to use for this request
+ # @option params [Symbol] :user_ip The IP of the user on who's behalf this request is made
+ # @return [GooglePlus::Person] a person object representing the person we're looking up,
+ # if it is found - otherwise, return nil
def self.get(user_id, params = {})
data = make_request(:get, "people/#{user_id}", params)
Person.new(JSON.parse(data)) if data
end
+ # Search for a person
+ # @param [String] query The query string to search for
+ # @option params [Symbol] :key A different API key to use for this request
+ # @option params [Symbol] :user_ip The IP of the user on who's behalf this request is made
+ # @return [GooglePlus::Cursor] a cursor for the people found in the search
def self.search(query, params = {})
params[:query] = URI.escape(query)
resource = 'people'
GooglePlus::Cursor.new(self, :get, resource, params)
end
- # get a cursor for activities for this user
+ # List the activities for this person
+ # @return [GooglePlus::Cursor] a cursor of activities for this person
def list_activities
GooglePlus::Activity.for_person(id)
end
+ # Load a new instance from an attributes hash
+ # Useful if you have the underlying response data for an object - Generally, what you
+ # want is #get though
+ # @return [GooglePlus::Person] A person constructed from the attributes hash
def initialize(hash)
load_hash(hash)
end

0 comments on commit 6b1f353

Please sign in to comment.