rentlinx 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6945492920d30e62b769a7b4b3c89b1e26e7be10
-  data.tar.gz: 07f11c4486e4e142632277a28fffa4a0b1e33573
+  metadata.gz: cedfa421e0893f1fb8ece12bd133929b75107c85
+  data.tar.gz: d2de51edd47f047a7244efa188e406b237ea964d
 SHA512:
-  metadata.gz: d72733d83b47e0bd1141b2c06d36d4ad19fe04e4e3b9d6469d8612211eb2a6ba8448a3fdf2adcc666cc2a2fa670d484a209db8f4fe4925a7f1ea4b6ba2342c83
-  data.tar.gz: 1cf99840f44b1c2f9ae1a86e99eddf16ec351cedddd7ee6c52c516542d2dd66330c06265dbac60435e367bcb5ae57637479b8ada6d4c2a71b11e5a7ba7b0a493
+  metadata.gz: 9c22c7e3ed1751a8863519d5b02563db53b47f939e6a9bfa39e87fb1a2453d2e16cc2d207da897b3dcc94274c0fe3c664b504bbf95bd0ad639acd4c9924a5824
+  data.tar.gz: 2f6c08a6f4643ba3b5c78c588d235fb6490fb7beeba556b7c2790b647a3b296d17e942235c613427a17e5354896e094550eecb69aa968c6110a572df403e0cf5

data/README.md

@@ -9,8 +9,39 @@ _rentlinx_client_ is a ruby wrapper for the RentLinx API.
 
 ## Installation
 
+To install from the command line, run: 
+
     gem install rentlinx
 
+To include in a rails app, include this line in your gemfile:
+
+    gem 'rentlinx'
+
+### Usage
+
+Configure like so:
+
+    Rentlinx.configure do |rentlinx|
+      rentlinx.username ENV['RENTLINX_USERNAME']
+      rentlinx.password ENV['RENTLINX_PASSWORD']
+      rentlinx.site_url 'https://rentlinx.com/api/v2'
+      rentlinx.log_level :error
+    end
+
+For all endpoints, attributes are defined by the API: https://www.rentlinx.com/mongoose/help
+
+Properties:
+
+    prop = Property.new(attributes)
+    prop.post # creates
+
+    prop.website = 'http://example.com'
+    prop.post # updates
+
+    prop = Property.from_id('property-id') # fetches
+
+Objects can be created for all endpoints supported by the Rentlinx API, including Units, Amenities, Photos, and Links. For more detailed information, see the [full documentation on rubygems](http://www.rubydoc.info/gems/rentlinx).
+
 ## Contributing and development
 
 Pull requests are welcome for this gem. New features require writing new
@@ -36,6 +67,12 @@ Not all rubocop's rules are set in stone, so once you are receiving only
 warnings testing rules that may not make sense, please comment on your pull
 request indicating you think the rules should be adjusted with your reasoning.
 
+### Documentation
+
+All new classes, modules, and public methods should be documented in the style
+of [yard](http://yardoc.org/). Modified classes and methods should have their
+documentation updated accordingly. Tests do not need documentation.
+
 ### Testing: Unit tests
 
 The second suite is running minitest. The simplest way to invoke our minitest
@@ -48,22 +85,6 @@ test files can be executed via:
 
     ruby -Ilib:test test/FILENAME.rb
 
-
-### Usage
-
-For all endpoints, attributes are defined by the API: https://www.rentlinx.com/mongoose/help
-
-Properties can be created, updated, and fetched from Rentlinx like so:
-
-    prop = Property.new(attributes)
-    prop.post # creates
-
-    prop.website = 'http://example.com'
-    prop.post # updates
-
-    prop = Property.from_id('property-id') # fetches
-
-
 ## Copyright and license
 
 Source released under the Simplified BSD License.

data/lib/rentlinx.rb

@@ -11,16 +11,29 @@ require 'rentlinx/models/unit_amenity'
 require 'rentlinx/models/property_link'
 require 'rentlinx/models/unit_link'
 
+# This is the main rentlinx module. All Rentlinx objects
+# and methods are namespaced under this module.
 module Rentlinx
   @username = nil
   @password = nil
   @site_url = nil
 
   class << self
+    # Allows the configuration of Rentlinx in a configure-block
+    # style.
+    #
+    # @example
+    #   Rentlinx.configure do |rentlinx|
+    #     rentlinx.username ENV['RENTLINX_USERNAME']
+    #     rentlinx.password ENV['RENTLINX_PASSWORD']
+    #     rentlinx.site_url 'https://rentlinx.com/api/v2'
+    #     rentlinx.log_level :error
+    #   end
     def configure(&block)
       block.call(self)
     end
 
+    # Sets and retrieves the username used to log in to Rentlinx
     def username(*args)
       if args.empty?
         @username
@@ -29,6 +42,7 @@ module Rentlinx
       end
     end
 
+    # Sets and retrieves the password used to log in to Rentlinx
     def password(*args)
       if args.empty?
         @password
@@ -37,6 +51,7 @@ module Rentlinx
       end
     end
 
+    # Sets and retrieves the URL where the API is hosted.
     def site_url(*args)
       if args.empty?
         @site_url
@@ -45,6 +60,8 @@ module Rentlinx
       end
     end
 
+    # Sets and retrieves the log level, currently only :error
+    # and :debug are supported
     def log_level(*args)
       if args.empty?
         @log_level
@@ -53,10 +70,12 @@ module Rentlinx
       end
     end
 
+    # The client object used for communicating with Rentlinx
     def client
       @client ||= Rentlinx::Client.new
     end
 
+    # The logger object
     def logger
       lgr = Logging.logger(STDOUT)
       lgr.level = (@log_level || :error)

data/lib/rentlinx/client.rb

@@ -9,6 +9,11 @@ require 'rentlinx/modules/amenity_client_methods'
 require 'rentlinx/modules/link_client_methods'
 
 module Rentlinx
+  # This class and its included modules encapsulate all
+  # communication directly with the Rentlinx API.
+  #
+  # It should not be interacted with, the objects provide
+  # all the functionality necessary to work with Rentlinx.
   class Client
     include Rentlinx::PropertyClientMethods
     include Rentlinx::UnitClientMethods
@@ -16,6 +21,14 @@ module Rentlinx
     include Rentlinx::AmenityClientMethods
     include Rentlinx::LinkClientMethods
 
+    # Returns a new instance of client. Avoid using.
+    #
+    # Note that the method {Rentlinx.client} initializes and caches
+    # an instance of the Rentlinx client. This method should be used
+    # instead of this one when interacting directly with the client
+    # to avoid making multiple connections to Rentlinx.
+    #
+    # Rentlinx must be configured before invoking this method.
     def initialize
       raise Rentlinx::NotConfigured if Rentlinx.username.nil? ||
                                        Rentlinx.password.nil? ||
@@ -25,6 +38,9 @@ module Rentlinx
       @api_token ||= authenticate(Rentlinx.username, Rentlinx.password)
     end
 
+    # Pushes an object's attributes out to Rentlinx
+    #
+    # @param object [Rentlinx::Base] the object to be posted
     def post(object)
       case object
       when Rentlinx::Property
@@ -38,6 +54,10 @@ module Rentlinx
       end
     end
 
+    # Unposts an object from Rentlinx
+    #
+    # @param type [Symbol] the type of object to be unposted
+    # @param id [String] the rentlinx id of the object to be unposted
     def unpost(type, id)
       case type
       when :property
@@ -49,6 +69,10 @@ module Rentlinx
       end
     end
 
+    # Pulls the attributes for an object from Rentlinx and instantiates it
+    #
+    # @param type [Symbol] the type of object to be fetched
+    # @param id [String] the rentlinx id of the object to be fetched
     def get(type, id)
       case type
       when :property

data/lib/rentlinx/default.rb

@@ -1,6 +1,7 @@
 require 'rentlinx/version'
 
 module Rentlinx
+  # The default headers for the Rentlinx client
   module Default
     USER_AGENT = "Rentlinx Ruby Client #{Rentlinx::VERSION}".freeze
 

data/lib/rentlinx/errors.rb

@@ -1,33 +1,48 @@
 require 'json'
 
 module Rentlinx
+  # Basic error class to be inherited from
+  #
+  # Use this error to rescue all types of Rentlinx errors
   class RentlinxError < StandardError
   end
 
+  # Thrown when instantiating an object with attributes
+  # that object does not support them
   class UnexpectedAttributes < RentlinxError
   end
 
+  # Thrown when posting or getting an invalid type
   class InvalidTypeParam < RentlinxError
   end
 
+  # Thrown when the Rentlinx client is initialized without first
+  # being configured
   class NotConfigured < RentlinxError
     def initialize
       super('Rentlinx is not configured.')
     end
   end
 
+  # Thrown when an object that does not pass validation tries
+  # to post or update
   class InvalidObject < RentlinxError
     def initialize(object)
       super("#{object.class} is invalid: #{object.error_messages}")
     end
   end
 
+  # Thrown when a group of objects is passed to a batch endpoint but
+  # cannot be posted because they belong to different properties
   class IncompatibleGroupOfObjectsForPost < RentlinxError
     def initialize(property)
       super("These objects cannot be grouped together ('#{property}' differ).")
     end
   end
 
+  # A general class of errors for handling issues in the communication with
+  # Rentlinx. To be inherited from, or thrown when the server returns a code
+  # not otherwise handled.
   class HTTPError < RentlinxError
     attr_reader :response
 
@@ -37,6 +52,7 @@ module Rentlinx
     end
   end
 
+  # Thrown when error code 400 (bad request) is received
   class BadRequest < HTTPError
     def initialize(response)
       default_message = 'The request sent to the server was invalid.'
@@ -49,24 +65,28 @@ module Rentlinx
     end
   end
 
+  # Thrown when error code 404 (not found) is received
   class NotFound < HTTPError
     def initialize(response)
       super(response, 'The item you requested could not be found on the remote server.')
     end
   end
 
+  # Thrown when error code 409 (conflict) is received
   class Conflict < HTTPError
     def initialize(response)
       super(response, 'There was a conflict on the remote server.')
     end
   end
 
+  # Thrown when error code 403 (forbidden) is received
   class Forbidden < HTTPError
     def initialize(response)
       super(response, 'You are not permitted to access the item you requested.')
     end
   end
 
+  # Thrown when 500 series error codes (internal server errors) are received
   class ServerError < HTTPError
     def initialize(response)
       super(response, 'The remote server has experienced an error.')

data/lib/rentlinx/models/base.rb

@@ -1,7 +1,20 @@
 require 'rentlinx/validators/attribute_processor_service'
 
 module Rentlinx
+  # This is the class on which all other Rentlinx classes are based,
+  # it encapsulates much of the important logic used by every class.
+  #
+  # It should never be instantiated on its own, use one of its
+  # subclasses.
   class Base
+    # Creates a new instance of the class, but the base class should
+    # never be directly instantiated.
+    #
+    # This method takes in the attributes for the new instance, runs
+    # them through the {AttributeProcessor} and saves them as instance
+    # variables.
+    #
+    # @param attrs [Hash] a hash of attributes to save.
     def initialize(attrs)
       @processor = AttributeProcessor.new(attrs.dup)
       attrs = @processor.process
@@ -12,30 +25,41 @@ module Rentlinx
       raise UnexpectedAttributes, "Unexpected Attributes: #{remaining_attrs.join(', ')}" if remaining_attrs.compact.size > 0
     end
 
+    # Provides a list of attributes supported by the class.
+    #
+    # @return an array of attribute keys
     def attributes
       self.class::ATTRIBUTES
     end
 
+    # Provides the list of required attributes for the class (a subset of Class.attributes)
+    #
+    # @return an array of attribute keys
     def required_attributes
       self.class::REQUIRED_ATTRIBUTES
     end
 
+    # Sends the object to Rentlinx
+    #
+    # @example
+    #     prop = Rentlinx::Property.new(attrs)
+    #     prop.post
     def post
       Rentlinx.client.post(self)
     end
 
+    # Removes the object from Rentlinx
+    #
+    # @example
+    #     prop = Rentlinx::Property.new(attrs)
+    #     prop.unpost
     def unpost
       Rentlinx.client.unpost(type, send(type.to_s + 'ID'))
     end
 
-    def self.unpost(id)
-      Rentlinx.client.unpost(type, id)
-    end
-
-    def self.get_from_id(type, id)
-      Rentlinx.client.get(type.to_sym, id)
-    end
-
+    # Converts the object to a hash
+    #
+    # @return a hash including the attributes and values
     def to_hash
       {}.tap do |hash|
         attributes.each do |at|
@@ -44,10 +68,16 @@ module Rentlinx
       end
     end
 
+    # Determines the validity of the object
+    #
+    # @return true if valid, false if invalid
     def valid?
       error_messages.empty?
     end
 
+    # Provides error messages on invalid objects
+    #
+    # @return a hash of error messages
     def error_messages
       @processor = AttributeProcessor.new(to_hash)
       @processor.process
@@ -63,6 +93,14 @@ module Rentlinx
 
     private
 
+    def self.unpost(id)
+      Rentlinx.client.unpost(type, id)
+    end
+
+    def self.get_from_id(type, id)
+      Rentlinx.client.get(type.to_sym, id)
+    end
+
     def type
       self.class.type
     end

data/lib/rentlinx/models/property.rb

@@ -3,6 +3,7 @@ require 'rentlinx/modules/amenityable'
 require 'rentlinx/modules/linkable'
 
 module Rentlinx
+  # An object that represents a Rentlinx property.
   class Property < Base
     ATTRIBUTES = [:companyID, :propertyID, :description, :address, :city, :state,
                   :zip, :marketingName, :hideAddress, :latitude, :longitude,
@@ -15,15 +16,29 @@ module Rentlinx
 
     attr_accessor(*ATTRIBUTES)
 
+    # Posts the property with all of its attached units.
+    #
+    # TODO: Discuss whether or not these kinds of methods are needed,
+    # or whether we should have post do everything every time.
     def post_with_units
       post
       units.each(&:post) unless units.nil? || units.empty?
     end
 
+    # The list of units attached to the property.
+    #
+    # If the units list is empty, it will query Rentlinx for the list
+    # of units stored on their end.
+    #
+    # @return a list of Rentlinx::Unit objects
     def units
       @units ||= get_units_for_property_id(propertyID)
     end
 
+    # Allows assigning a list of units to the property.
+    #
+    # @param unit_list [Array] a list of Rentlinx::Unit objects
+    # @return the updated list of Rentlinx::Unit objects
     def units=(unit_list)
       @units = unit_list.map do |unit|
         unit.propertyID = propertyID
@@ -31,21 +46,31 @@ module Rentlinx
       end
     end
 
+    # Queries rentlinx and builds a property with the given ID.
+    #
+    # The returned property will have all the attributes Rentlinx
+    # has for the property on their end.
+    #
+    # @param id [String] the rentlinx id of the property
+    # @return a Rentlinx::Property that is up to date with the remote one
     def self.from_id(id)
       get_from_id(:property, id)
     end
 
     include Rentlinx::Photoable
+    # For internal use.
     def photo_class
       Rentlinx::PropertyPhoto
     end
 
     include Rentlinx::Amenityable
+    # For internal use.
     def amenity_class
       Rentlinx::PropertyAmenity
     end
 
     include Rentlinx::Linkable
+    # For internal use.
     def link_class
       Rentlinx::PropertyLink
     end

data/lib/rentlinx/models/property_amenity.rb

@@ -1,4 +1,5 @@
 module Rentlinx
+  # An amenity on a propery
   class PropertyAmenity < Base
     ATTRIBUTES = [:details, :name, :propertyID]
 
@@ -6,6 +7,9 @@ module Rentlinx
 
     attr_accessor(*ATTRIBUTES)
 
+    # Converts the object to a hash
+    #
+    # @return a hash with the details and name of the link
     def to_hash
       { details: details, name: name }
     end

data/lib/rentlinx/models/property_link.rb

@@ -1,4 +1,5 @@
 module Rentlinx
+  # A link on a property
   class PropertyLink < Base
     ATTRIBUTES = [:propertyID, :title, :url]
 
@@ -6,6 +7,9 @@ module Rentlinx
 
     attr_accessor(*ATTRIBUTES)
 
+    # Converts the link to a hash
+    #
+    # @return a hash with the url and title of the link
     def to_hash
       { url: url, title: title }
     end

data/lib/rentlinx/models/property_photo.rb

@@ -1,4 +1,5 @@
 module Rentlinx
+  # A photo on a property
   class PropertyPhoto < Base
     ATTRIBUTES = [:url, :caption, :position, :propertyID, :unitID]
 
@@ -6,6 +7,9 @@ module Rentlinx
 
     attr_accessor(*ATTRIBUTES)
 
+    # Converts the photo to a hash
+    #
+    # @return a hash with the url and caption of the photo
     def to_hash
       { url: url, caption: caption }
     end

data/lib/rentlinx/models/unit.rb

@@ -3,6 +3,7 @@ require 'rentlinx/modules/amenityable'
 require 'rentlinx/modules/linkable'
 
 module Rentlinx
+  # An object that represents a Rentlinx unit.
   class Unit < Base
     ATTRIBUTES = [:unitID, :propertyID, :name, :description, :rent, :maxRent,
                   :deposit, :maxDeposit, :squareFeet, :maxSquareFeet,
@@ -16,24 +17,37 @@ module Rentlinx
     attr_accessor(*ATTRIBUTES)
 
     include Rentlinx::Photoable
+    # For internal use
     def photo_class
       Rentlinx::UnitPhoto
     end
 
     include Rentlinx::Amenityable
+    # For internal use
     def amenity_class
       Rentlinx::UnitAmenity
     end
 
     include Rentlinx::Linkable
+    # For internal use
     def link_class
       Rentlinx::UnitLink
     end
 
+    # Gets all the photos for a unit.
+    #
+    # @return a list of Rentlinx::UnitPhoto objects
     def photos
       super.select { |p| p.unitID == unitID }
     end
 
+    # Queries rentlinx and builds a unit with the given ID
+    #
+    # The returned unit will have all the attributes Rentlinx
+    # has for the unit on their end.
+    #
+    # @param id [String] the rentlinx id of the unit
+    # @return a Rentlinx::Unit that is up to date with the remote one
     def self.from_id(id)
       get_from_id(:unit, id)
     end

data/lib/rentlinx/models/unit_amenity.rb

@@ -1,4 +1,5 @@
 module Rentlinx
+  # An amenity on a unit
   class UnitAmenity < PropertyAmenity
     ATTRIBUTES += [:unitID]
 

data/lib/rentlinx/models/unit_link.rb

@@ -1,4 +1,5 @@
 module Rentlinx
+  # A link on a unit
   class UnitLink < PropertyLink
     ATTRIBUTES += [:unitID]
 

data/lib/rentlinx/models/unit_photo.rb

@@ -1,4 +1,5 @@
 module Rentlinx
+  # A photo on a unit
   class UnitPhoto < PropertyPhoto
     REQUIRED_ATTRIBUTES += [:unitID]
   end

data/lib/rentlinx/modules/amenity_client_methods.rb

@@ -1,5 +1,11 @@
 module Rentlinx
+  # Client methods for amenities
+  #
+  # TODO: Refactor into AttachmentClientMethods
   module AmenityClientMethods
+    # Submits amenities to the batch endpoint on Rentlinx
+    #
+    # @param amenities [Array] an array of amenity objects
     def post_amenities(amenities)
       return if amenities.nil?
       raise(Rentlinx::InvalidObject, amenities.find { |a| !a.valid? }) unless amenities.all?(&:valid?)
@@ -12,6 +18,11 @@ module Rentlinx
       post_unit_amenities(unit_amenities) unless unit_amenities.empty?
     end
 
+    # Unposts all amenities for a unit or property by posting
+    # an empty list to the batch update endpoint.
+    #
+    # @param object [Rentlinx::Property, Rentlinx::Unit] the object
+    #               whos amenities should be unposted
     def unpost_amenities_for(object)
       case object
       when Rentlinx::Unit
@@ -23,6 +34,11 @@ module Rentlinx
       end
     end
 
+    # Gets all the amenities for a property, dividing them into
+    # {Rentlinx::PropertyAmenity} and {Rentlinx::UnitAmenity} objects
+    #
+    # @param id [String] an ID for a property posted to Rentlinx
+    # @return an array of unit and property amenities
     def get_amenities_for_property_id(id)
       data = request('GET', "properties/#{id}/amenities")['data']
       data.map do |amenity_data|
@@ -37,11 +53,19 @@ module Rentlinx
       return []
     end
 
+    # Gets all the amenities for a unit
+    #
+    # @param unit [Rentlinx::Unit] the unit to fetch amenities for
+    # @return an array of unit amenities
     def get_amenities_for_unit(unit)
       amenities = get_amenities_for_property_id(unit.propertyID)
       amenities.select { |a| defined? a.unitID && a.unitID == unit.unitID }
     end
 
+    # Unposts a single amenity
+    #
+    # @param amenity [Rentlinx::UnitAmenity, Rentlinx::PropertyAmenity] the
+    #   amenity to be unposted
     def unpost_amenity(amenity)
       case amenity
       when Rentlinx::UnitAmenity

data/lib/rentlinx/modules/amenityable.rb

@@ -1,10 +1,19 @@
 module Rentlinx
+  # A module that encapsulates all ammenity related logic for {Rentlinx::Property} and
+  # {Rentlinx::Unit} objects. All of these methods can be called on Properties and Units.
+  #
+  # TODO: Refactor into BaseAble class along with {Linkable} and {Photoable}
   module Amenityable
+    # Posts the object with its associated amenities
+    #
+    # TODO: Discuss whether or not these kinds of methods are needed,
+    # or whether we should have post do everything every time.
     def post_with_amenities
       post
       post_amenities
     end
 
+    # Posts the object's amenities
     def post_amenities
       return if @amenities.nil?
 
@@ -15,6 +24,9 @@ module Rentlinx
       end
     end
 
+    # Loads and caches the list of amenities from Rentlinx.
+    #
+    # @return a list of amenities
     def amenities
       return @amenities if @amenities
 
@@ -26,6 +38,10 @@ module Rentlinx
         end
     end
 
+    # Allows assignment of amenities to the object.
+    #
+    # @param amenity_list [Array] an array of amenities
+    # @return the list of amenities on the object
     def amenities=(amenity_list)
       @amenities = amenity_list.map do |amenity|
         amenity.propertyID = propertyID
@@ -34,6 +50,13 @@ module Rentlinx
       end
     end
 
+    # Builds a single amenity and attaches it to the object. This method
+    # conveniently assigns the propertyID and unitID (if present) of the
+    # parent object, so these need not be passed.
+    #
+    # @param options [Hash] the attributes for the amenity, defined in
+    #   {Rentlinx::PropertyAmenity}
+    # @return the updated list of amenities on the object
     def add_amenity(options)
       options.merge!(propertyID: propertyID)
       options.merge!(unitID: unitID) if defined? unitID

data/lib/rentlinx/modules/link_client_methods.rb

@@ -1,5 +1,15 @@
 module Rentlinx
+  # Client methods for Amenities
+  #
+  # TODO: Refactor into AttachmentClientMethods
   module LinkClientMethods
+    # Posts an array of links to Rentlinx
+    #
+    # This uses the batch endpoint, so all links must be associated with
+    # the same property. They can be on different units, so long as all units
+    # are on the same property.
+    #
+    # @param links [Array] an array of links which all have the same propertyID
     def post_links(links)
       return if links.nil?
 
@@ -13,6 +23,11 @@ module Rentlinx
       post_unit_links(unit_links) unless unit_links.empty?
     end
 
+    # Unposts all links for unit or property by posting an empty
+    # array to the batch update endpoint
+    #
+    # @param object [Rentlinx::Property, Rentlinx::Unit] the object whos
+    #               links should be unposted
     def unpost_links_for(object)
       case object
       when Rentlinx::Unit
@@ -24,6 +39,9 @@ module Rentlinx
       end
     end
 
+    # Gets all the links for a given property, including unit links
+    #
+    # @param id [String] the id of the property
     def get_links_for_property_id(id)
       data = request('GET', "properties/#{id}/links")['data']
       data.map do |link_data|
@@ -38,11 +56,17 @@ module Rentlinx
       return []
     end
 
+    # Gets all the links for a given unit
+    #
+    # @param unit [Rentlinx::Unit] the unit for which links should be fetched
     def get_links_for_unit(unit)
       links = get_links_for_property_id(unit.propertyID)
       links.select { |link| defined?(link.unitID) && link.unitID == unit.unitID }
     end
 
+    # Unposts a specific link
+    #
+    # @param link [Rentlinx::UnitLink, Rentlinx::PropertyLink] the link to be unposted
     def unpost_link(link)
       case link
       when Rentlinx::UnitLink

data/lib/rentlinx/modules/linkable.rb

@@ -1,10 +1,19 @@
 module Rentlinx
+  # A module that encapsulates all link related logic for {Rentlinx::Property} and
+  # {Rentlinx::Unit} objects. All of these methods can be called on Properties and Units.
+  #
+  # TODO: Refactor into BaseAble class along with {Amenityable} and {Photoable}
   module Linkable
+    # Posts the object with associated links
+    #
+    # TODO: Discuss whether or not these kinds of methods are needed,
+    # or whether we should have post do everything every time.
     def post_with_links
       post
       post_links
     end
 
+    # Posts the links for an object
     def post_links
       return if @links.nil?
 
@@ -15,6 +24,9 @@ module Rentlinx
       end
     end
 
+    # Loads and caches the list of amenities from Rentlinx.
+    #
+    # @return a list of amenities
     def links
       @links ||=
         if defined? unitID

data/lib/rentlinx/modules/photo_client_methods.rb

@@ -1,4 +1,7 @@
 module Rentlinx
+  # Client methods for photos
+  #
+  # TODO: Refactor into AttachmentClientMethods
   module PhotoClientMethods
     def post_photos(photos)
       return if photos.nil?

data/lib/rentlinx/modules/photoable.rb

@@ -1,4 +1,8 @@
 module Rentlinx
+  # A module that encapsulates all photo related logic for {Rentlinx::Property} and
+  # {Rentlinx::Unit} objects. All of these methods can be called on Properties and Units.
+  #
+  # TODO: Refactor into BaseAble class along with {Linkable} and {Amenityable}
   module Photoable
     def post_with_photos
       post

data/lib/rentlinx/modules/property_client_methods.rb

@@ -1,5 +1,10 @@
 module Rentlinx
+  # Client methods for property
   module PropertyClientMethods
+    # Gets all the units for a given property id
+    #
+    # @param id [String] the id of the property
+    # @return a list of Rentlinx::Unit objects
     def get_units_for_property_id(id)
       data = request('GET', "properties/#{id}/units")['data']
       data.map do |unit_data|

data/lib/rentlinx/modules/unit_client_methods.rb

@@ -1,4 +1,5 @@
 module Rentlinx
+  # Client methods for units. No public methods.
   module UnitClientMethods
     private
 

data/lib/rentlinx/validators/address_validator.rb

@@ -0,0 +1,13 @@
+module Rentlinx
+  # Validator for addresses
+  #
+  # Ensures they are three or more characters.
+  class AddressValidator < BaseValidator
+    private
+
+    def validate
+      return if !@value.nil? && @value.length > 2
+      @error = "'#{@value}' is not a valid address, an address must be 3 characters or more."
+    end
+  end
+end

data/lib/rentlinx/validators/attribute_processor_service.rb

@@ -1,4 +1,5 @@
 require 'rentlinx/validators/base_validator'
+require 'rentlinx/validators/address_validator'
 require 'rentlinx/validators/city_validator'
 require 'rentlinx/validators/phone_validator'
 require 'rentlinx/validators/state_validator'
@@ -6,22 +7,37 @@ require 'rentlinx/validators/url_validator'
 require 'rentlinx/validators/zip_validator'
 
 module Rentlinx
+  # Provides processing and validation for attributes on {Rentlinx::Property} and
+  # {Rentlinx::Unit} objects
   class AttributeProcessor
     attr_reader :errors
     attr_reader :processed_attrs
 
+    # @param attrs [Hash] the attributes to be processed
     def initialize(attrs)
       @attrs = attrs
       @processed_attrs = @attrs
       @errors = {}
     end
 
+    # Processes the attributes, both validating them and processing them
+    # into a format suitable for Rentlinx.
+    #
+    # This method also populates the errors attribute, so it must be run
+    # before calling .valid? or querying for errors.
+    #
+    # Currently, phone number, state, zip, and leads URL are validated.
+    # They are passed into their own validator objects: {PhoneValidator},
+    # {StateValidator}, {ZipValidator}, and {UrlValidator}
+    #
+    # @return the processed attributes ready to submit to Rentlinx
     def process
       validators = { phoneNumber: PhoneValidator,
                      state: StateValidator,
                      zip: ZipValidator,
                      leadsURL: UrlValidator,
-                     city: CityValidator }
+                     city: CityValidator,
+                     address: AddressValidator }
 
       @attrs.each do |field, val|
         next unless validators.keys.include?(field)
@@ -33,6 +49,9 @@ module Rentlinx
       @processed_attrs
     end
 
+    # Determines the validity of the attributes it contains.
+    #
+    # @return [Boolean] true if valid, false if not
     def valid?
       @errors.size == 0
     end

data/lib/rentlinx/validators/base_validator.rb

@@ -1,21 +1,33 @@
 module Rentlinx
+  # This is the base validator. It encapsulates all the logic shared
+  # between the various validators.
   class BaseValidator
     attr_reader :error
 
+    # Creates a new instance of the class, and validates but
+    # BaseValidator should never be directly instantiated.
     def initialize(val)
       @value = val
       @error = ''
       validate
     end
 
+    # Determines the validity of the attribute.
+    #
+    # @return true if valid, false if invalid
     def valid?
       @error == ''
     end
 
+    # The processed value after validation of the attribute.
+    #
+    # @return a processed value, a stripped phone number for example
     def processed_value
       @value
     end
 
+    private
+
     def value_blank?
       @value.nil? || @value == ''
     end

data/lib/rentlinx/validators/city_validator.rb

@@ -1,4 +1,7 @@
 module Rentlinx
+  # Validator for cities
+  #
+  # Ensures they are three or more characters.
   class CityValidator < BaseValidator
     private
 

data/lib/rentlinx/validators/phone_validator.rb

@@ -1,7 +1,9 @@
 require 'phony'
 
 module Rentlinx
+  # Validator for phone numbers
   class PhoneValidator < BaseValidator
+    # Validates and normalizes the phone number with Phony
     def processed_value
       return '' if value_blank?
       return @value unless valid?

data/lib/rentlinx/validators/state_validator.rb

@@ -1,4 +1,7 @@
 module Rentlinx
+  # Validator for two letter state codes
+  #
+  # Contains a list of all the states Rentlinx permits
   class StateValidator < BaseValidator
     STATES = %w(AK AL AR AS AZ CA CO CT DC DE FL GA GU HI IA ID IL IN KS KY LA
                 MA MD ME MI MN MO MP MS MT NC ND NE NH NJ NM NV NY OH OK OR PA

data/lib/rentlinx/validators/url_validator.rb

@@ -1,4 +1,5 @@
 module Rentlinx
+  # Validator for URLs
   class UrlValidator < BaseValidator
     private
 

data/lib/rentlinx/validators/zip_validator.rb

@@ -1,4 +1,5 @@
 module Rentlinx
+  # Validator for US postal codes
   class ZipValidator < BaseValidator
     private
 

data/lib/rentlinx/version.rb

@@ -1,3 +1,5 @@
+# This is the main rentlinx module. All Rentlinx objects
+# and methods are namespaced under this module.
 module Rentlinx
-  VERSION = '0.9.0'
+  VERSION = '0.9.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rentlinx
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - AppFolio, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-30 00:00:00.000000000 Z
+date: 2015-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httpclient
@@ -95,6 +95,7 @@ files:
 - lib/rentlinx/modules/photoable.rb
 - lib/rentlinx/modules/property_client_methods.rb
 - lib/rentlinx/modules/unit_client_methods.rb
+- lib/rentlinx/validators/address_validator.rb
 - lib/rentlinx/validators/attribute_processor_service.rb
 - lib/rentlinx/validators/base_validator.rb
 - lib/rentlinx/validators/city_validator.rb
@@ -123,9 +124,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: API Wrapper for the Rentlinx API
 test_files: []
-has_rdoc: