Permalink
Browse files

Add @since tag to methods, and minor README reformatting

Adding the @since tag to our methods lets people see whether the
method they are trying to use is available in the version of
octocat_herder they're using, or if they need to upgrade in order to
use it.
  • Loading branch information...
1 parent 28c4f9c commit 46e26d9deda993b9049c109cc58646379d4b874c @jhelwig jhelwig committed Jul 24, 2011
View
@@ -2,4 +2,4 @@ lib/**/*.rb
bin/*
-
features/**/*.feature
-LICENSE.txt
+LICENSE
View
File renamed without changes.
View
@@ -39,16 +39,26 @@ Quick start:
## Contributing to octocat-herder
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Check out the latest master to make sure the feature hasn't been
+ implemented or the bug hasn't been fixed yet
+
+* Check out the issue tracker to make sure someone already hasn't
+ requested it and/or contributed it
+
* Fork the project
+
* Start a feature/bug-fix branch
+
* Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-## Copyright
+* Make sure to add tests for it. This is important so I don't break it
+ in a future version unintentionally.
+
+* Please try not to mess with the Rakefile, version, or history. If
+ you want to have your own version, or is otherwise necessary, that
+ is fine, but please isolate to its own commit so I can cherry-pick
+ around it.
-Copyright (c) 2011 Jacob Helwig. See LICENSE.txt for
-further details.
+## Copyright
+Copyright (c) 2011 Jacob Helwig. See LICENSE for further details.
View
@@ -11,10 +11,14 @@
class OctocatHerder
# The instance of OctocatHerder::Connection used for making API
# requests.
+ #
+ # @since 0.0.1
attr_reader :connection
# Get a new OctocatHerder for use with the GitHub v3 API.
#
+ # @since 0.0.1
+ # @see OctocatHerder::Connection.new
# @param [Hash] options Passed to OctocatHerder::Connection.new
def initialize(options={})
@connection = OctocatHerder::Connection.new(options)
@@ -23,6 +27,7 @@ def initialize(options={})
# Fetch an OctocatHerder::User by using OctocatHerder::User.fetch
# and the OctocatHerder::Connection from #connection
#
+ # @since 0.0.1
# @param [String] user_name The login name of the GitHub user to retrieve.
def user(user_name)
OctocatHerder::User.fetch(user_name, connection)
View
@@ -16,19 +16,19 @@ class OctocatHerder
module Base
# The re-hydrated JSON retrieved from the GitHub API.
#
+ # @since 0.0.1
# @return [Hash]
attr_reader :raw
# Our OctocatHerder::Connection, so we can make more requests
# based on the information we retrieved from the GitHub API.
#
+ # @since 0.0.1
# @return [OctocatHerder::Connection]
attr_reader :connection
- # This isn't meant to be consumed publicly. It's meant to be used
- # by the various class and instance methods that actually make the
- # API requests.
- #
+ # @api private
+ # @since 0.0.1
# @param [Hash] raw_hash The re-hydrated JSON received from the GitHub API via OctocatHerder::Connection.
# @param [OctocatHerder::Connection] conn If not provided requests will be unauthenticated.
def initialize(raw_hash, conn = OctocatHerder::Connection.new)
@@ -39,6 +39,8 @@ def initialize(raw_hash, conn = OctocatHerder::Connection.new)
# We use the +method_missing+ magic to create accessors for the
# information we got back from the GitHub API. You can get a list
# of all of the available things from #available_attributes.
+ #
+ # @since 0.0.1
def method_missing(id, *args)
unless @raw and @raw.keys.include?(id.id2name)
raise NoMethodError.new("undefined method #{id.id2name} for #{self}:#{self.class}")
@@ -50,6 +52,7 @@ def method_missing(id, *args)
# This returns a list of the things that the API request returned
# to us.
#
+ # @since 0.0.1
# @return [Array<String>] Names of available methods providing additional detail about the object.
def available_attributes
attrs = []
@@ -77,6 +80,7 @@ module ClassMethods
# This is intended to be used by the various classes
# implementing the GitHub API end-points.
#
+ # @since development
# @param [OctocatHerder::Connection] conn An instance of OctocatHerder::Connection to use for the request.
# @param [String] end_point The part of the API URL after 'https://api.github.com', including the leading '/'.
# @param [Hash] options A Hash of options to be passed down to HTTParty, and additionally +:paginated+ to let us know if we should be retrieving _all_ pages of a paginated result and +:params+ which will be constructed into a query string using OctocatHerder::Base.query_string_from_params.
@@ -115,6 +119,7 @@ def raw_get(conn, end_point, options={})
# [first] The first page of results.
# [prev] The immediate previous page of results.
#
+ # @since development
# @param [Hash] headers
# @param ['next', 'last', 'first', 'prev] type
def page_from_headers(headers, type)
@@ -126,7 +131,8 @@ def page_from_headers(headers, type)
# Convenience method to generate URL query strings.
#
- # [+params+] A Hash of key/values to be turned into a URL query string. Does not support nested data.
+ # @since development
+ # @param [Hash] params A Hash of key/values to be turned into a URL query string. Does not support nested data.
def query_string_from_params(params)
return '' if params.keys.empty?
@@ -139,10 +145,13 @@ def query_string_from_params(params)
# Intended to be overridden in classes using OctocatHerder::Base,
# so they can make the methods they define show up in
# #available_attributes.
+ #
+ # @since 0.0.1
def additional_attributes
[]
end
+ # @since 0.0.1
def parse_date_time(date_time)
return nil unless date_time
@@ -9,12 +9,18 @@ class Connection
base_uri 'https://api.github.com'
# User name to use when doing basic HTTP authentication.
+ #
+ # @since 0.0.1
attr_reader :user_name
# Password to use when doing basic HTTP authentication.
+ #
+ # @since 0.0.1
attr_reader :password
# The OAuth2 token to use when doing OAuth2 authentication.
+ #
+ # @since 0.0.1
attr_reader :oauth2_token
# If provided a hash of login information, the Connection will attempt to make authenticated requests.
@@ -27,7 +33,11 @@ class Connection
# If no hash is provided, then unauthenticated requests will be
# made.
#
+ # @since 0.0.1
# @param [Hash<Symbol => String>] options Login information
+ # @option options [String] :user_name
+ # @option options [String] :password
+ # @option options [String] :oauth2_token
def initialize(options={})
raise ArgumentError.new(
"OctocatHerder::Connection does not accept: #{options.class}"
@@ -61,6 +71,8 @@ def initialize(options={})
# Small wrapper around the standard HTTParty +get+ method, which
# handles adding authentication information to the API request.
+ #
+ # @since 0.0.1
def get(end_point, options={})
request_options = options.merge(httparty_options)
if httparty_options.has_key?(:headers) and options.has_key(:headers)
@@ -16,6 +16,7 @@ class PullRequest
# Query either the open or closed pull requests for a given
# repository.
#
+ # @since 0.0.1
# @param [String] owner_login The login name of the repository owner.
# @param [String] repository_name The name of the repository itself.
# @param ['open', 'closed'] status Defaults to querying open pull requests.
@@ -40,6 +41,7 @@ def self.find_for_repository(owner_login, repository_name, status = 'open', conn
# Query the open pull requests for a given repository.
#
+ # @since 0.0.1
# @param [String] owner_login The login name of the repository owner.
# @param [String] repository_name The name of the repository itself.
# @param [OctocatHerder::Connection] conn Defaults to unauthenticated requests.
@@ -50,6 +52,7 @@ def self.find_open_for_repository(owner_login, repository_name, conn = OctocatHe
# Query the closed pull requests for a given repository.
#
+ # @since 0.0.1
# @param [String] owner_login The login name of the repository owner.
# @param [String] repository_name The name of the repository itself.
# @param [OctocatHerder::Connection] conn Defaults to unauthenticated requests.
@@ -60,6 +63,7 @@ def self.find_closed_for_repository(owner_login, repository_name, conn = Octocat
# Query information about a specific pull request.
#
+ # @since 0.0.1
# @param [String] owner_login The login name of the repository owner.
# @param [String] repository_name The name of the repository itself.
# @param [String, Integer] pull_request_number The pull request to retrieve.
@@ -75,8 +79,8 @@ def self.fetch(owner_login, repository_name, pull_request_number, conn = Octocat
new(nil, request, conn)
end
- # @note Not intended for public consumption.
- #
+ # @api private
+ # @since 0.0.1
# @param [Hash] raw_hash The 'overview' information retrieved from the pull request listing API.
# @param [Hash] raw_detail_hash The full information available by querying information about a specific pull request.
# @param [OctocatHerder::Connection] conn Defaults to unauthenticated requests.
@@ -92,6 +96,7 @@ def initialize(raw_hash, raw_detail_hash = nil, conn = OctocatHerder::Connection
# listing. This will query information about the specific pull
# request, which will get us all of the available details.
#
+ # @since 0.0.1
# @return [self]
def get_detail
return if @raw_detail_hash
@@ -108,6 +113,7 @@ def get_detail
# the GitHub API, then check +@raw_detail_hash+ (populating it if
# needed).
#
+ # @since 0.0.1
# @return [String]
def method_missing(id, *args)
super
@@ -122,6 +128,7 @@ def method_missing(id, *args)
#
# @note Since this is returned by the pull request API itself, this can be used without making an additional API request.
#
+ # @since 0.0.1
# @return [String] Avatar URL
def user_avatar_url
return @raw['user']['avatar_url'] if @raw
@@ -132,6 +139,7 @@ def user_avatar_url
#
# @note Since this is returned by the pull request API itself, this can be used without making an additional API request.
#
+ # @since 0.0.1
# @return [String] User URL
def user_url
return @raw['user']['url'] if @raw
@@ -142,6 +150,7 @@ def user_url
#
# @note Since this is returned by the pull request API itself, this can be used without making an additional API request.
#
+ # @since 0.0.1
# @return [Integer] User ID
def user_id
return @raw['user']['id'] if @raw
@@ -152,6 +161,7 @@ def user_id
#
# @note Since this is returned by the pull request API itself, this can be used without making an additional API request.
#
+ # @since 0.0.1
# @return [String] User login name
def user_login
return @raw['user']['login'] if @raw
@@ -162,6 +172,7 @@ def user_login
#
# @note This is cached locally to the individual pull request, but will make an additional API request to populate it initially.
#
+ # @since 0.0.1
# @return [OctocatHerder::User]
def user
@user ||= OctocatHerder::User.fetch(user_login, connection)
@@ -170,6 +181,7 @@ def user
# The login name of the person that merged the pull request, or
# +nil+ if it has not been merged yet.
#
+ # @since 0.0.1
# @return [String, nil]
def merged_by_login
return nil unless merged
@@ -181,6 +193,7 @@ def merged_by_login
# The ID number of the person that merged the pull request, or
# +nil+ if it has not been merged yet.
#
+ # @since 0.0.1
# @return [String, nil]
def merged_by_id
return nil unless merged
@@ -192,6 +205,7 @@ def merged_by_id
# The URL to the avatar image of the person that merged the pull
# request, or +nil+ if it has not been merged yet.
#
+ # @since 0.0.1
# @return [String, nil]
def merged_by_avatar_url
return nil unless merged
@@ -203,6 +217,7 @@ def merged_by_avatar_url
# The URL of the person that merged the pull request, or +nil+ if
# it has not been merged yet.
#
+ # @since 0.0.1
# @return [String, nil]
def merged_by_url
return nil unless merged
@@ -216,6 +231,7 @@ def merged_by_url
#
# @note This is cached locally to the individual pull request, but will make an additional API request to populate it initially.
#
+ # @since 0.0.1
# @return [OctocatHerder::User, nil]
def merged_by
return nil unless merged
@@ -225,27 +241,31 @@ def merged_by
# When the pull request was first created.
#
+ # @since 0.0.1
# @return [Time]
def created_at
parse_date_time(@raw_detail_hash['created_at'])
end
# When the pull request was last updated.
#
+ # @since 0.0.1
# @return [Time]
def updated_at
parse_date_time(@raw_detail_hash['updated_at'])
end
# When the pull request was closed, or +nil+ if it is still open.
#
+ # @since 0.0.1
# @return [Time, nil]
def closed_at
parse_date_time(@raw_detail_hash['closed_at'])
end
# When the pull request was merged, or +nil+ if it hasn't been merged.
#
+ # @since 0.0.1
# @return [Time, nil]
def merged_at
parse_date_time(@raw_detail_hash['merged_at'])
@@ -254,6 +274,7 @@ def merged_at
# Information about what is being asked to be merged in the pull
# request.
#
+ # @since 0.0.1
# @return [OctocatHerder::PullRequest::Repo]
def head
get_detail
@@ -264,6 +285,7 @@ def head
# Information about what the pull request was based on in the pull
# request.
#
+ # @since 0.0.1
# @return [OctocatHerder::PullRequest::Repo]
def base
get_detail
@@ -274,6 +296,7 @@ def base
# A Hash representation of the pull request. Combines +@raw+, and
# +@raw_detail_hash+ into a single hash.
#
+ # @since 0.0.2
# @return [Hash]
def to_hash
raw = @raw || {}
@@ -287,6 +310,9 @@ def to_hash
# Give a full listing of the available information, since we
# define some of our own methods, and don't have everything in
# +@raw+.
+ #
+ # @api private
+ # @since 0.0.1
def additional_attributes
attrs = ['user_avatar_url', 'user_url', 'user_id', 'user_login']
Oops, something went wrong.

0 comments on commit 46e26d9

Please sign in to comment.