clever-ruby 0.6.0 → 0.6.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MTI0OGY0NTY3MDg0ODc1NGE0OTJlNmE1NGQxMjVmZGJlNGFjMzFlMA==
+    OWYwYWY4NjMwMjdjYTY4MmIzNjE3ZDQ5NjkwMTNlYTQ5MTU5ZWQ2Mg==
   data.tar.gz: !binary |-
-    ZTJjNGFhNTlkZTMxYWM0NjMxNjVjOGZmNmI1NjUyMTg4ZjIwZWI0YQ==
+    ZTVmYWMwZjFmZTRhZTQ2ZTc1ZGEwMDhmOGJmNTY2OTg3NThmYTFlZg==
 SHA512:
   metadata.gz: !binary |-
-    NGNiNGM5OGM3ZjYwNjYyZGIyMmZlM2VjZmFmNWQxNjdhMjBmY2M1ZDBlMDY0
-    NWZhZTM4MTE3MmIyOTkxNTQ0ODdhODAxODVhNGI0N2U1OGY3NjdhMWM1Njc3
-    ZTlmZTY0NjQxZjUyNTliNGRiZjI1MTIzZDllYzRiNDU2MjVjOWM=
+    ZTE1ZTAyNGY5ZWJmMThlZWZmNzY5NjQxYTdmNzVmOGM4MTA4MThjMmRiY2E2
+    MjRhZDZiOWUxYzRjNDY5ZjYzZWEyMmM1ZjdjYjFiMjMzNWE1YWYyODQ4N2Q2
+    ZjVkMDk2YjlmZTk1ZjJhOGM1YTMyYTIyMDlkZjlmNmEyYmU3M2I=
   data.tar.gz: !binary |-
-    NGZjMjNkYjgxNGQxYWE0NWY2MGZkNjgzNzZmMThlZDIyZGI5MTk3OTcwMzI2
-    OTJlZGMwZjQwZjI1NDMyNjVjZGZjN2E3ZTVhMDMyNzg3OWVjOGM1NGViNTBk
-    MzdkNWE3ODhkZGExZGVlNzk4NWMyZGYwMDQwOGE5NjlkMDUyOTY=
+    NmRkYmU3M2FjNDIzNmUyNzg1NzVhMTU5MTA4YTUxNTk0Y2U3YTlhNjliZGJj
+    OTdiNDVmMTM1N2RhNjI2MmE3ZGVkNjU0ZTNhOGE4OGViMTJhYWZmYTFkZGZk
+    NTYxMDFiY2M3M2Q0NTYwNGZiMzdmZmFkZDM0OGE2ZmVmNDhmODg=

data/.gitignore

@@ -3,6 +3,7 @@
 .bundle
 .config
 .yardoc
+doc_coverage.txt
 .rvmrc
 .ruby-version
 .ruby-gemset

data/.yardopts

@@ -0,0 +1,2 @@
+--markup markdown
+--title clever-ruby

data/CHANGELOG.md

@@ -1,4 +1,9 @@
-## 0.6.0 (2014-09-09)
+## 0.6.1 (2014-09-10)
+
+* Add YARD documentation
+* Remove unused Clever::Student.photo method
+
+## 0.6.0 (2014-09-10)
 
 * Add ActiveRecord-style find and count methods to all APIResources (#37)
 

data/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://drone.ops.clever.com/github.com/Clever/clever-ruby/status.svg?branch=master)](https://drone.ops.clever.com/github.com/Clever/clever-ruby)
 
-Ruby bindings to the Clever API.
+Ruby bindings to the Clever API. [Documentation](http://rubydoc.info/gems/clever-ruby/frames)
 
 ## Installation
 
@@ -24,6 +24,19 @@ Or install it yourself as:
 $ gem install clever-ruby
 ```
 
+## Usage
+
+Configure clever-ruby to use your Clever token:
+
+```ruby
+Clever.configure do |config|
+  config.token = 'YOUR-API-TOKEN'
+end
+```
+
+See the [documentation](http://rubydoc.info/gems/clever-ruby/frames) for
+further details.
+
 ## Run tests
 
 To run all tests:
@@ -46,16 +59,22 @@ $ rake lint
 
 Running specific tests is not currently supported.
 
-## Usage
+## Documentation
 
-Configure clever-ruby to use your Clever API key:
+To generate it to `./doc`:
 
-```ruby
-Clever.configure do |config|
-  config.api_key = 'YOUR-API-KEY'
-end
+```bash
+$ rake doc
 ```
 
+To see documentation coverage:
+
+```bash
+$ rake doc-coverage
+```
+
+and then view `doc_coverage.txt`.
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -9,13 +9,18 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = true
 end
 
-require 'rdoc/task'
+require 'yard'
 require 'clever-ruby/version'
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "clever-ruby #{Clever::VERSION}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+YARD::Rake::YardocTask.new :doc
+
+require 'yardstick/rake/measurement'
+Yardstick::Rake::Measurement.new(:'doc-coverage') do |measurement|
+  measurement.output = 'doc_coverage.txt'
+end
+
+require 'yardstick/rake/verify'
+Yardstick::Rake::Verify.new(:'doc-coverage-verify') do |verify|
+  verify.threshold = 100
 end
 
 require 'rubocop/rake_task'
@@ -28,4 +33,6 @@ end
 task default: [] do
   Rake::Task[:test].execute
   Rake::Task[:lint].execute
+  Rake::Task[:'doc-coverage'].execute
+  Rake::Task[:'doc-coverage-verify'].execute
 end

data/clever-ruby.gemspec

@@ -25,7 +25,9 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'minitest',      '~> 4.4.0'
   gem.add_development_dependency 'shoulda',       '~> 3.3.2'
-  gem.add_development_dependency 'rdoc',          '~> 3.12'
+  gem.add_development_dependency 'yard',          '~> 0.8.7'
+  gem.add_development_dependency 'yardstick',     '~> 0.9.9'
+  gem.add_development_dependency 'redcarpet',     '~> 3.1.2'
   gem.add_development_dependency 'vcr',           '~> 2.4.0'
   gem.add_development_dependency 'webmock',       '~> 1.9.0'
   gem.add_development_dependency 'pry',           '~> 0.10.1'

data/lib/clever-ruby/api_operations/list.rb

@@ -3,7 +3,16 @@ module Clever
     # A list of API resource instances
     module List
       # Class methods for those that include List
+      # @api public
       module ClassMethods
+        # Get all elements of a resource
+        # @api public
+        # @deprecated This can be costly since it places all matching elements
+        #   in memory. Instead just iterate over the collection using each.
+        # @param filters [Hash] parameters to apply, as per the Clever API spec
+        # @return [Array] array of all elements matching the request
+        # @example
+        #   Clever::District.all
         def all(filters = {})
           accum = []
           Clever::APIOperations::PageList.new(url, filters).each do |page|
@@ -12,6 +21,25 @@ module Clever
           accum
         end
 
+        # Get elements of a resource. Supports 1 or more ids, or open-ended query
+        # @api public
+        # @param id [String, Array, nil] ID or array of ids to match, or nil
+        #   for query
+        # @param filters [Hash, nil] Query parameters to pass, as per Clever API spec
+        # @return [Clever::APIResource, Clever::APIOperations::ResultsList]
+        #   single resource or iterable list of results
+        # @raise [ArgumentError] Bad ID/IDs provided
+        # @example
+        #   # Get first 20 clever districts
+        #   districts = Clever::District.find.take 20
+        #
+        #   # Get specific district
+        #   id = '...'
+        #   district = Clever::District.find id
+        #
+        #   # Get districts with given ids
+        #   ids = ['...', '...']
+        #   districts = Clever::District.find ids
         def find(id = nil, filters = {})
           if id.is_a? Array
             unless id.select { |e| !Clever::Util.valid_id? e }.empty?
@@ -30,6 +58,12 @@ module Clever
           end
         end
 
+        # Requests number of elements matching the query
+        # @api public
+        # @param filters [Hash, nil] Query parameters to pass, as per Clever API spec
+        # @return [Integer] Number of elements matching
+        # @example
+        #   num_districts = Clever::District.count
         def count(filters = {})
           filters[:count] = true
           response = Clever.request :get, url, filters
@@ -37,6 +71,9 @@ module Clever
         end
       end
 
+      # Add ClassMethods to classes that include List
+      # @api private
+      # @return [nil]
       def self.included(base)
         base.extend ClassMethods
       end

data/lib/clever-ruby/api_operations/page.rb

@@ -4,6 +4,11 @@ module Clever
     class Page
       include Enumerable
 
+      # Request a page of data and store the results in this instance
+      # @api private
+      # @return [Clever::APIOperations::Page]
+      # @example
+      #   page = Page.new '/v1.1/districts'
       def initialize(uri, filters = {})
         @uri = uri
         @filters = filters
@@ -16,16 +21,31 @@ module Clever
         end
       end
 
-      # Gets next page if one is present, nil otherwise.
+      # Gets next page if one is present, nil otherwise
+      # @api private
+      # @return [Clever::APIOperations::Page, nil] Next page, or nil if last
+      # @example
+      #   next_page = page.next
+      #   unless next_page.nil?
+      #     next_page.each do |elem| puts elem; end
       def next
         @links.key?(:next) ? Page.new(@links[:next]) : nil
       end
 
+      # Iterate over all elements in the page
+      # @api private
+      # @return [Array] List of all elements
+      # @example
+      #   page.each { |elem| puts elem }
       def each(&blk)
         @list.each(&blk)
       end
 
-      # TODO: remove this
+      # Get all elements in page
+      # @api private
+      # @return [Array] List of all elements
+      # @example
+      #   all_elems = page.all
       def all
         accum = []
         each do |elem|

data/lib/clever-ruby/api_operations/pagelist.rb

@@ -4,11 +4,23 @@ module Clever
     class PageList
       include Enumerable
 
+      # Create a new PageList, without making any requests immediately
+      # @api private
+      # @return [PageList]
       def initialize(uri, filters = {})
         @uri = uri
         @filters = filters
       end
 
+      # Iterate through each page, making requests as you iterate
+      # @api private
+      # @return [nil]
+      # @example
+      #   pagelist.each do |page|
+      #     page.each do |elem|
+      #       puts elem
+      #     end
+      #   end
       def each
         page = Page.new @uri, @filters
         until page.nil?
@@ -17,6 +29,11 @@ module Clever
         end
       end
 
+      # Convert PageList into a ResultsList for easier iteration
+      # @api private
+      # @return [Clever::APIOperations::ResultsList]
+      # @example
+      #   pagelist.to_results_list.each { |elem| puts elem }
       def to_results_list
         Clever::APIOperations::ResultsList.new self
       end

data/lib/clever-ruby/api_operations/results_list.rb

@@ -4,10 +4,21 @@ module Clever
     class ResultsList
       include Enumerable
 
+      # Create a results list from a PageList
+      # @api private
+      # @return [ResultsList]
       def initialize(pagelist)
         @pages = pagelist
       end
 
+      # Iterate over results list
+      # @api public
+      # @return [nil]
+      # @example
+      #   results = Clever::District.find # returns a ResultsList
+      #   results.each do |district|
+      #     puts district.name
+      #   end
       def each
         @pages.each do |page|
           page.each do |elem|

data/lib/clever-ruby/api_resource.rb

@@ -1,6 +1,9 @@
 module Clever
   # Superclass of API resources in the Clever API
   class APIResource < CleverObject
+    # Get URL for a resource
+    # @api private
+    # @return [String] url to query for a resource
     def self.url
       if self == APIResource
         fail NotImplementedError, 'APIResource is an abstract class. You should perform actions '\
@@ -10,6 +13,9 @@ module Clever
       "v1.1/#{CGI.escape shortname.downcase}s"
     end
 
+    # Get URL for an instance of a resource
+    # @api private
+    # @return [String] url to query for an instance of a resource
     def url
       id = self['id']
       unless id
@@ -20,28 +26,56 @@ module Clever
       "#{self.class.url}/#{CGI.escape id}"
     end
 
+    # Request the current resource data and update this object
+    # @api private
+    # @return [APIResource] The updated resource instance
     def refresh
       response = Clever.request :get, url
       refresh_from response[:data]
       self
     end
 
+    # Get hypermedia links for this resource instance
+    # @api private
+    # @return [Array] list of links for this resource instance
     def links
       response = Clever.request :get, url
       response[:links]
     end
 
+    # Get an instance of a resource
+    # @api public
+    # @param id [String] ID of the instance to find
+    # @return [APIResource] resource instance
+    # @example
+    #   id = '...'
+    #   district = Clever::District.retrieve id
     def self.retrieve(id)
       instance = new id
       instance.refresh
       instance
     end
 
+    # Request resource instances by following hypermedia links
+    # @api private
+    # @return [Array] List of resources found
     def get_linked_resources(resource_type, filters = {})
       Util.convert_to_clever_object Clever.request(:get, get_uri(resource_type), filters)[:data]
     end
 
-    class << self; attr_reader :linked_resources; end
+    class << self
+      # Get a list of nested resources in the Clever API for this resource
+      # @api private
+      # @return [Array] List of resources nested under this resource
+      attr_reader :linked_resources
+    end
+
+    # Create an instance of APIResource, defining links to nested resources
+    # @api public
+    # @param [String] id of object to instantiate
+    # @return [APIResoruce] resource instance
+    # @example
+    #   Clever::District.new '531fabe082d522cds8e22'
     def initialize(id)
       super id
 

data/lib/clever-ruby/clever_object.rb

@@ -10,27 +10,48 @@ module Clever
     # The default :id method is deprecated and isn't useful to us
     undef :id if method_defined? :id
 
+    # Create a CleverObject. Only for inheritance purposes
+    # @api private
+    # @return [CleverObject]
     def initialize(id = nil)
       @values = {}
       @values[:id] = id if id
     end
 
+    # Construct a CleverObject from the values it should contain. Requires :id
+    # @api private
+    # @return [CleverObject]
     def self.construct_from(values)
       obj = new values[:id]
       obj.refresh_from values
       obj
     end
 
+    # Convert to a pretty-printed JSON string
+    # @api public
+    # @return [String] JSON representation of the CleverObject
+    # @example
+    #   puts obj.to_s
     def to_s
       Clever::JSON.dump @values, pretty: true
     end
 
+    # Convert this object to a detailed human-readable string
+    # @api public
+    # @return [String] Detailed representation of the CleverObject
+    # @example
+    #   puts obj.inspect
     def inspect
       id_string = (respond_to?(:id) && !id.nil?) ? " id=#{id}" : ''
       "#<#{self.class}:0x#{object_id.to_s(16)}#{id_string}> JSON: " +
         Clever::JSON.dump(@values, pretty: true)
     end
 
+    # Populate this object with the values passed in
+    # @api private
+    # @param values [Hash] values to set
+    # @param partial [Boolean] whether to replace existing keys or start fresh
+    # @return [CleverObject]
     def refresh_from(values, partial = false)
       removed = partial ? Set.new : Set.new(@values.keys - values.keys)
       added = Set.new(values.keys - @values.keys)
@@ -50,49 +71,114 @@ module Clever
       end
     end
 
+    # Access a value by key
+    # @api public
+    # @param k [String, Symbol] Key to access
+    # @return [Object] Value at that key
+    # @example
+    #   district = Clever::District.retrieve id
+    #   puts district[:name]
     def [](k)
       k = k.to_sym if k.is_a? String
       @values[k]
     end
 
+    # Set an attribute
+    # @api public
+    # @param k [String, Symbol] Key to set
+    # @param v [Object] Value to set
+    # @return [Object]
+    # @example
+    #   district = Clever::District.retrieve id
+    #   district[:name] = "New district name"
     def []=(k, v)
       send :"#{k}=", v
     end
 
+    # Get list of keys in object
+    # @api public
+    # @return [Array] list of keys
+    # @example
+    #   district = Clever::District.retrieve id
+    #   puts district.keys
     def keys
       @values.keys
     end
 
+    # Get list of values in object
+    # @api public
+    # @return [Array] list of values
+    # @example
+    #   district = Clever::District.retrieve id
+    #   puts district.values
     def values
       @values.values
     end
 
+    # Convert to a JSON string
+    # @api public
+    # @return [String] JSON representation of the CleverObject
+    # @example
+    #   district = Clever::District.retrieve id
+    #   puts district.to_json
     def to_json
       Clever::JSON.dump @values
     end
 
+    # Unsure
+    # @todo Figure out what this is intended for and how it should behave
+    # @api private
+    # @return [Object]
     def as_json(*a)
       @values.as_json(*a)
     end
 
+    # Convert to a Hash
+    # @api public
+    # @return [Hash] Hash representation of the CleverObject
+    # @example
+    #   district = Clever::District.retrieve id
+    #   data = district.to_hash
     def to_hash
       @values
     end
 
+    # Iterate over key-value pairs in the Object
+    # @api public
+    # @return [Hash] Values in the object
+    # @example
+    #   district = Clever::District.retrieve id
+    #   district.each do |k, v|
+    #     puts "#{k}: #{v}"
+    #   end
     def each(&blk)
       @values.each(&blk)
     end
 
+    # Compare two CleverObjects by values
+    # @api public
+    # @param other [CleverObject] Object to compare
+    # @return [Boolean] equality
+    # @example
+    #   districtOne = Clever::District.retrieve id
+    #   districtTwo = Clever::District.retrieve id
+    #   districtOne == districtTwo  #=> true
     def ==(other)
       values == other.values if other.respond_to? :values
     end
 
     protected
 
+    # Fetch CleverObject's metaclass
+    # @api private
+    # @return [Object]
     def metaclass
       class << self; self; end
     end
 
+    # Remove accessors
+    # @api private
+    # @return [Object]
     def remove_accessors(keys)
       metaclass.instance_eval do
         keys.each do |k|
@@ -104,6 +190,9 @@ module Clever
       end
     end
 
+    # Add accessors
+    # @api private
+    # @return [Object]
     def add_accessors(keys)
       metaclass.instance_eval do
         keys.each do |k|
@@ -115,12 +204,21 @@ module Clever
       end
     end
 
+    # Defines attributes that the CleverObject can optionally have
+    # @api private
+    # @return [Array] List of optional attributes
     def optional_attributes
       fail NotImplementedError 'Please define #optional_attributes as a list of the '\
         'attributes on this resource that may not be present and thus should return nil' \
         'instead of raising a NoMethodError.'
     end
 
+    # Automatically adds methods for accessing keys with dot notation
+    # @api private
+    # @return [Object]
+    # @example
+    #   district = Clever::District.retrieve id
+    #   district.name = "New district name"
     def method_missing(name, *args)
       return @values[name] if @values.key? name
       return nil if optional_attributes.include? name

data/lib/clever-ruby/configuration.rb

@@ -1,8 +1,24 @@
 module Clever
   # Configuration for accessing the Clever API over HTTP
   class Configuration
-    attr_accessor :api_key, :token, :api_base
+    # Access API Key
+    # @api private
+    # @return [String]
+    attr_accessor :api_key
 
+    # Access API Token
+    # @api private
+    # @return [String]
+    attr_accessor :token
+
+    # Access API base URL
+    # @api private
+    # @return [String]
+    attr_accessor :api_base
+
+    # Initialize configuration
+    # @api private
+    # @return [Clever::Configuration]
     def initialize
       @api_key  = nil
       @token = nil

data/lib/clever-ruby/district.rb

@@ -4,11 +4,15 @@ module Clever
     include Clever::APIOperations::List
     @linked_resources = [:schools, :teachers, :sections, :students, :events]
 
+    # @see Clever::CleverObject.optional_attributes
+    # @api private
+    # @return [Array]
     def optional_attributes
       # All of a district's attributes are required.
       []
     end
 
+    # TODO: remove
     [:school_pages, :teacher_pages, :section_pages, :student_pages, :event_pages].each do |name|
       define_method(name) do |filters = {}|
         Clever::APIOperations::PageList.new get_uri(name.to_s.gsub('_page', '')), filters
@@ -17,6 +21,9 @@ module Clever
 
     private
 
+    # Get the URI for a hypermedia link
+    # @api private
+    # @return [String]
     def get_uri(resource_type)
       refresh
       links.find { |link| link[:rel] == resource_type }[:uri]

data/lib/clever-ruby/errors/clever_error.rb

@@ -1,11 +1,37 @@
 module Clever
   # Represents an error outputted bythe Clever API
   class CleverError < StandardError
+    # Access error Message
+    # @api public
+    # @return [String]
+    # @example
+    #   puts err.message
     attr_reader :message
+
+    # Access HTTP status of error
+    # @api public
+    # @return [Integer]
+    # @example
+    #   puts err.http_status
     attr_reader :http_status
+
+    # Access HTTP body of error
+    # @api public
+    # @return [String]
+    # @example
+    #   puts err.http_body
     attr_reader :http_body
+
+    # Access JSON body of error
+    # @api public
+    # @return [String]
+    # @example
+    #   puts err.json_body
     attr_reader :json_body
 
+    # Create CleverError instance
+    # @api private
+    # @return [Clever::CleverError]
     def initialize(message = nil, http_status = nil, http_body = nil, json_body = nil)
       @message = message
       @http_status = http_status
@@ -13,6 +39,11 @@ module Clever
       @json_body = json_body
     end
 
+    # Output CleverError instance as a human-readable string
+    # @api public
+    # @return [String]
+    # @example
+    #   puts err.to_s
     def to_s
       status_string = @http_status.nil? ? '' : "(Status #{@http_status}) "
       "#{status_string}#{@message}"

data/lib/clever-ruby/errors/invalid_request_error.rb

@@ -1,8 +1,14 @@
 module Clever
   # An invalid request to the Clever API
   class InvalidRequestError < CleverError
+    # Access param
+    # @api private
+    # @return [Object]
     attr_accessor :param
 
+    # Create new InvalidRequestError
+    # @api private
+    # @return [Clever::InvalidRequestError]
     def initialize(message, param, http_status = nil, http_body = nil, json_body = nil)
       super message, http_status, http_body, json_body
       @param = param

data/lib/clever-ruby/event.rb

@@ -3,30 +3,55 @@ module Clever
   class Event < APIResource
     include Clever::APIOperations::List
 
+    # Optional attributes
+    # @see Clever::CleverObject.optional_attributes
+    # @api private
+    # @return [Array]
     def optional_attributes
       []
     end
 
+    # Get object corresponding to this event
+    # @api public
+    # @return [CleverObject]
+    # @example
+    #   district = event.object
     def object
       klass = Util.types_to_clever_class type_pieces[0]
       klass ||= CleverObject
       klass.construct_from data[:object]
     end
 
+    # Get previous attributes before the event
+    # @api public
+    # @return [Hash]
+    # @example
+    #   prev = event.previous_attributes
     def previous_attributes
       data[:previous_attributes]
     end
 
+    # Get action taken in Event
+    # @api public
+    # @return [String]
+    # @example
+    #   action = event.action
     def action
       type_pieces[1]
     end
 
+    # Get URL for events endpoint
+    # @api private
+    # @return [String]
     def self.url
       'v1.1/events'
     end
 
     private
 
+    # Split type of Event into pieces
+    # @api private
+    # @return [Array]
     def type_pieces
       type.split '.'
     end

data/lib/clever-ruby/json.rb

@@ -2,18 +2,30 @@ module Clever
   # Helpers for handling JSON responses
   module JSON
     if MultiJson.respond_to? :dump
+      # Dump as a JSON string
+      # @api private
+      # @return [String]
       def self.dump(*args)
         MultiJson.dump(*args)
       end
 
+      # Load a JSON string to an object
+      # @api private
+      # @return [Object]
       def self.load(*args)
         MultiJson.load(*args, symbolize_keys: true)
       end
     else
+      # Dump as a JSON string
+      # @api private
+      # @return [String]
       def self.dump(*args)
         MultiJson.encode(*args)
       end
 
+      # Load a JSON string to an object
+      # @api private
+      # @return [Object]
       def self.load(*args)
         MultiJson.decode(*args, symbolize_keys: true)
       end

data/lib/clever-ruby/school.rb

@@ -4,6 +4,10 @@ module Clever
     include Clever::APIOperations::List
     @linked_resources = [:teachers, :students, :sections, :districts, :events]
 
+    # Optional attributes
+    # @see Clever::CleverObject.optional_attributes
+    # @api private
+    # @return [Array]
     def optional_attributes
       [:state_id, :sis_id, :nces_id, :low_grade, :high_grade, :principal, :location, :phone]
     end

data/lib/clever-ruby/section.rb

@@ -4,6 +4,10 @@ module Clever
     include Clever::APIOperations::List
     @linked_resources = [:teachers, :students, :schools, :districts, :events]
 
+    # Optional attributes
+    # @see Clever::CleverObject.optional_attributes
+    # @api private
+    # @return [Array]
     def optional_attributes
       [:teacher, :course_name, :course_description, :course_number, :period, :grade, :term]
     end

data/lib/clever-ruby/student.rb

@@ -4,21 +4,13 @@ module Clever
     include Clever::APIOperations::List
     @linked_resources = [:teachers, :sections, :schools, :districts, :events, :contacts]
 
+    # Optional attributes
+    # @see Clever::CleverObject.optional_attributes
+    # @api private
+    # @return [Array]
     def optional_attributes
       [:student_number, :state_id, :location, :gender, :dob, :grade, :frl_status,
        :race, :hispanic_ethnicity, :email, :credentials]
     end
-
-    def photo
-      return @values[:photo] if @values.key? :photo
-      response = Clever.request :get, photo_url
-      @values[:photo] = response[:data][:data]
-    end
-
-    private
-
-    def photo_url
-      url + '/photo'
-    end
   end
 end

data/lib/clever-ruby/teacher.rb

@@ -4,6 +4,10 @@ module Clever
     include Clever::APIOperations::List
     @linked_resources = [:sections, :students, :schools, :districts, :events, :grade_levels]
 
+    # Optional attributes
+    # @see Clever::CleverObject.optional_attributes
+    # @api private
+    # @return [Array]
     def optional_attributes
       [:email, :teacher_number, :title]
     end

data/lib/clever-ruby/util.rb

@@ -1,10 +1,17 @@
 module Clever
-  # LibraryhHelper methods
+  # Library helper methods
   module Util
+    # Check if a given ID is a valid format (MongoDB BSON ObjectID)
+    # @api private
+    # @param id [String] ID to check
+    # @return [Boolean] Whether or not it was valid
     def self.valid_id?(id)
       id.is_a?(String) && !(/^[0-9a-fA-F]{24}$/.match(id).nil?)
     end
 
+    # Replace APIResource objects with their ids in data structures
+    # @api private
+    # @return [Object] Original data structure with objects replaced by ids
     def self.objects_to_ids(h)
       case h
       when APIResource
@@ -20,6 +27,9 @@ module Clever
       end
     end
 
+    # Convert the name of a resource to its APIResource class
+    # @api private
+    # @return [APIResource]
     def self.types_to_clever_class(type)
       types = {
         'students'  => Student,
@@ -32,6 +42,9 @@ module Clever
       types.fetch type
     end
 
+    # Convert an object containing data from Clever into a CleverObject
+    # @api private
+    # @return [CleverObject]
     def self.convert_to_clever_object(resp)
       case resp
       when Array
@@ -48,6 +61,9 @@ module Clever
       end
     end
 
+    # Check if a file is readable
+    # @api private
+    # @return [Boolean]
     def self.file_readable(file)
       File.open(file) {}
     rescue
@@ -56,10 +72,16 @@ module Clever
       true
     end
 
+    # URL encode a key
+    # @api private
+    # @return [String]
     def self.encode_key(key)
       URI.escape key.to_s, Regexp.new("[^#{URI::PATTERN::UNRESERVED}]")
     end
 
+    # Flatten a params hash into an array
+    # @api private
+    # @return [Array]
     def self.flatten_params(params, parent_key = nil)
       result = []
       params.each do |key, value|
@@ -75,6 +97,9 @@ module Clever
       result
     end
 
+    # Flatten a nested params array into a flat array
+    # @api private
+    # @return [Array]
     def self.flatten_params_array(value, calculated_key)
       result = []
       value.each do |elem|

data/lib/clever-ruby/version.rb

@@ -1,4 +1,4 @@
 # Clever Ruby library
 module Clever
-  VERSION = '0.6.0'
+  VERSION = '0.6.1'
 end

data/lib/clever-ruby.rb

@@ -40,27 +40,50 @@ require 'clever-ruby/errors/invalid_request_error'
 # Clever Ruby library
 module Clever
   class << self
+    # Global configuration for using Clever
+    # @api public
+    # @example Configure your API key
+    #   Clever.configure do |config|
+    #     config.api_key = 'YOUR-API-KEY'
+    #   end
+    # @return [Object]
     def configure
       yield configuration
     end
 
+    # Retrieve your stored API key
+    # @api private
+    # @return [String] API key
     def api_key
       configuration.api_key
     end
 
+    # Retrieve your stored API token
+    # @api private
+    # @return [String] API token
     def token
       configuration.token
     end
 
+    # Retrieve the global Clever configuration object
+    # @api private
+    # @return [Hash] API configuration object
     def configuration
       @configuration ||= Clever::Configuration.new
     end
 
+    # Retrieve the URL of the Clever API being used
+    # @api private
+    # @return [String] API url
     def api_url(url = '')
       configuration.api_base + url
     end
   end
 
+  # Convert a hash of params to a query string. Does not prepend the leading '?'
+  # @api private
+  # @param params [Hash] Parameters to stringify
+  # @return [String] Query string
   def self.convert_to_query_string(params = nil)
     if params && params.count
       params_arr = Util.flatten_params(params).map do |p|
@@ -72,6 +95,12 @@ module Clever
     end
   end
 
+  # Generate the URL and payload for a request based on data about the request
+  # @api private
+  # @param method [Symbol] HTTP method used
+  # @param url [String] URL to send to
+  # @param params [Hash] Parameters to send
+  # @return [String, String] URL and payload to send via HTTP
   def self.create_payload(method, url, params)
     case method.to_s.downcase.to_sym
     when :get, :head, :delete
@@ -88,6 +117,9 @@ module Clever
     [url, payload]
   end
 
+  # Create options hash that specifies an HTTP request from request data
+  # @api private
+  # @return [Hash] parameters for executing a request
   def self.create_request_opts(method, url, params, headers)
     params = Util.objects_to_ids params
     url = api_url url
@@ -110,6 +142,10 @@ module Clever
     opts
   end
 
+  # Confirm API key or token are globally configured
+  # @api private
+  # @return [nil]
+  # @raise [AuthenticationError] Error if no authentication present
   def self.check_authorization
     unless Clever.api_key || Clever.token
       fail AuthenticationError, 'No API key provided. (HINT: set your API key using '\
@@ -118,6 +154,14 @@ module Clever
     end
   end
 
+  # Send an HTTP request to the Clever API
+  # @api private
+  # @param method [Symbol] HTTP method used
+  # @param url [String] URL to send to
+  # @param params [Hash] parameters to send with the request
+  # @param headers [Hash] headers to send with the request
+  # @return [Hash] parsed JSON response
+  # @raise [APIError] Error if API fails to return valid JSON
   def self.request(method, url, params = nil, headers = {})
     check_authorization
     opts = create_request_opts method, url, params, headers
@@ -138,6 +182,11 @@ module Clever
 
   private
 
+  # Execute an HTTP request safely
+  # @api private
+  # @param opts [Hash] Definition of the request to make
+  # @return [String] Request results
+  # @raise [APIConnectionError] Request failure
   def self.execute_request(opts)
     begin
       request = RestClient::Request.execute opts
@@ -164,6 +213,11 @@ module Clever
     request
   end
 
+  # Translate errors thrown by RestClient into standardized APIConnectionErrors
+  # @api private
+  # @param e [Error] Error to handle
+  # @return [nil]
+  # @raise [APIConnectionError] Standardized error for request failures
   def self.handle_restclient_error(e)
     case e
     when RestClient::ServerBrokeConnection, RestClient::RequestTimeout
@@ -180,6 +234,12 @@ module Clever
     fail APIConnectionError, message
   end
 
+  # Translate errors returned as JSON by the Clever API into CleverErrors
+  # @api private
+  # @param rcode [Integer] response code
+  # @param rbody [String] response body
+  # @return [nil]
+  # @raise [CleverError] Clever error corresponding to the failure observed
   def self.handle_api_error(rcode, rbody)
     begin
       error_obj = Clever::JSON.load rbody
@@ -201,6 +261,9 @@ module Clever
     end
   end
 
+  # Generate an InvalidRequestError
+  # @api private
+  # @return [InvalidRequestError]
   def self.invalid_request_error(error, rcode, rbody, error_obj)
     if error.is_a? Hash
       InvalidRequestError.new error[:message], error[:param], rcode, rbody, error_obj
@@ -209,10 +272,16 @@ module Clever
     end
   end
 
+  # Generate an AuthenticationError
+  # @api private
+  # @return [AuthenticationError]
   def self.authentication_error(error, rcode, rbody, error_obj)
     AuthenticationError.new error[:message], rcode, rbody, error_obj
   end
 
+  # Generate an APIError
+  # @api private
+  # @return [APIError]
   def self.api_error(error, rcode, rbody, error_obj)
     APIError.new error[:message], rcode, rbody, error_obj
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clever-ruby
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Clever Dev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-10 00:00:00.000000000 Z
+date: 2014-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -81,19 +81,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 3.3.2
 - !ruby/object:Gem::Dependency
-  name: rdoc
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: 0.8.7
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: 0.8.7
+- !ruby/object:Gem::Dependency
+  name: yardstick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.9
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.9
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.1.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.1.2
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -175,6 +203,7 @@ files:
 - .drone.yml
 - .gitignore
 - .rubocop.yml
+- .yardopts
 - CHANGELOG.md
 - Gemfile
 - LICENSE