eaternet 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 202273f23326e002f8e4a03d631b324d71025969
-  data.tar.gz: d817710bb5054fe8af26a6550e0e41454e4b0aa7
+  metadata.gz: 9c214305218f45f7fc0f0110e0a20262dc89c1b3
+  data.tar.gz: b3713a441f427f7157999e8152e82a36bc6ac30c
 SHA512:
-  metadata.gz: feac8796ac69bc065bc16385d1a46469aa99d158bd3adbaae8303627af3653278618ac368ae403cc903355c997fa1d7e6721d93f4e594aebfe1efd2e63e40987
-  data.tar.gz: 6792b804fa1c37a490fd5ac8b93e88cf6357efec2b481d631d5a6a24440a015ee8269b5dcb95ebc38dfa6ebf675264d12d40a29850890aba8fdb9aed32bf7e64
+  metadata.gz: ace2d1b0f63390feee961ccdabede4f35792d746003726ba676d28f571ca18de77510a11e5f937e2f0f693297280eb2cb9cb3c58974a96bb7047d3e7145bff79
+  data.tar.gz: defe8a3e5cf85ccf3788e6fcb7a298a5e39261eb839b6834ab01f0cda797302926ca89435da362106b44a7e54c5527c9e369877e853e81ee2666fed2504ff7fe

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --name-tag required:"Required"

data/lib/eaternet/lives_1_0/adapter.rb

@@ -4,31 +4,31 @@ module Eaternet
     #   and optionally {#violations}, {#feed_info}, and {#legends} to
     #   implement a custom Lives 1.0 data source adapter.
     class Adapter
-      # Required.
+      # @required Yes
       # @return [Enumerable<Business>]
       def businesses
         fail 'Override this to return an Enumerable of Business'
       end
 
-      # Required.
+      # @required Yes
       # @return [Enumerable<Inspection>]
       def inspections
         fail 'Override this to return an Enumerable of Inspection'
       end
 
-      # Optional.
+      # @required No
       # @return [Enumerable<Violation>]
       def violations
         fail 'Optionally override this to return an Enumerable of Violation'
       end
 
-      # Optional.
+      # @required No
       # @return [FeedInfo]
       def feed_info
         fail 'Optionally override this to return a FeedInfo'
       end
 
-      # Optional.
+      # @required No
       # @return [Enumerable<Legend>]
       def legends
         fails 'Optionally override this to return an Enumerable of Legend'

data/lib/eaternet/lives_1_0/business.rb

@@ -48,7 +48,8 @@ module Eaternet
     #   information. For example: +14159083801
     #   @return [String]
     #
-    # @see http://www.yelp.com/healthscores#businesses LIVES/Business
+    # @see http://www.yelp.com/healthscores#businesses LIVES / Business
+    #   specification
     class Business < ValidatedObject
       attr_accessor :business_id, :name, :address, :city, :state,
                     :postal_code, :latitude, :longitude, :phone_number

data/lib/eaternet/lives_1_0/feed_info.rb

@@ -2,32 +2,60 @@ require 'eaternet/validated_object'
 
 module Eaternet
   module Lives_1_0
+    # Contains info about the feed itself.
+    #
     # @see http://www.yelp.com/healthscores#feed_info LIVES / Feed Information
+    #   specification
     class FeedInfo < ValidatedObject
-      attr_accessor :feed_date, :feed_version, :municipality_name,
-                    :municipality_url, :contact_email
-
+      # This regular expression for checking email addresses is based on one
+      # from one of Ryan Bates’ excellent screencasts.
       # See http://railscasts.com/episodes/211-validations-in-rails-3
       EMAIL_REGEX = /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i
       URL_REGEX = %r{\Ahttps?:/}
 
-      validates :feed_date,
-                type: Date,
-                presence: true
-      validates :feed_version,
-                type: String,
-                presence: true
-      validates :municipality_name,
-                type: String,
-                presence: true
-      validates :municipality_url,
-                type: String,
-                format: { with: URL_REGEX },
-                allow_nil: true
-      validates :contact_email,
-                type: String,
-                format: { with: EMAIL_REGEX },
-                allow_nil: true
+      # Date that the feed was generated.
+      #
+      # @required Yes
+      # @return [Date]
+      attr_accessor :feed_date
+      validates     :feed_date, presence: true, type: Date
+
+      # Version of the LIVES specification used to generate this feed.
+      # For example ‘0.4.1’.
+      #
+      # @required Yes
+      # @return [String]
+      attr_accessor :feed_version
+      validates     :feed_version, presence: true, type: String
+
+      # Name of the municipality providing this feed. For example
+      # ‘San Francisco’ or ‘Multnomah County’.
+      #
+      # @required Yes
+      # @return [String]
+      attr_accessor :municipality_name
+      validates     :municipality_name, presence: true, type: String
+
+      # URL of the publishing municipality’s website.
+      #
+      # @required No
+      # @return [String]
+      attr_accessor :municipality_url
+      validates     :municipality_url,
+                    type: String,
+                    format: { with: URL_REGEX },
+                    allow_nil: true
+
+      # Email address of the person to contact regarding invalid data in
+      # this feed.
+      #
+      # @required No
+      # @return [String]
+      attr_accessor :contact_email
+      validates     :contact_email,
+                    type: String,
+                    format: { with: EMAIL_REGEX },
+                    allow_nil: true
     end
   end
 end

data/lib/eaternet/lives_1_0/inspection.rb

@@ -1,17 +1,19 @@
-# coding: utf-8
 require 'eaternet/validated_object'
 
 module Eaternet
   module Lives_1_0
     # Information about an inspectors’ visit to a businesses.
+    #
+    # @todo Clean up the Yard doc.
     # @see http://www.yelp.com/healthscores#inspections LIVES / Inspections
+    #   specification
     class Inspection < ValidatedObject
       ZERO_TO_ONE_HUNDRED_AND_BLANK = (0..100).to_a + ['']
 
-      # @!attribute [rw] business_id
-      #   Unique identifier of the business for which this inspection
-      #   was done. Required.
-      #   @return [String]
+      # Unique identifier of the business for which this inspection
+      # was done. Required.
+      #
+      # @return [String]
       attr_accessor :business_id
       validates :business_id,
                 type: String,
@@ -24,8 +26,8 @@ module Eaternet
       #   associated score. (For example, some municipalities don’t associate
       #   a follow-up inspection with a score.)
       #   @return [Integer] if it's a scored inspection
-      #   @return [String] if it's an un-scored inspection, then the return value
-      #     will be an empty string.
+      #   @return [String] if it's an un-scored inspection, then the return
+      #     value will be an empty string.
       attr_accessor :score
       validates :score,
                 inclusion: { in: ZERO_TO_ONE_HUNDRED_AND_BLANK },
@@ -50,15 +52,14 @@ module Eaternet
       #   @return [String]
       attr_accessor :description
 
-      validates :type,
-                inclusion: { in: %w(initial routine followup complaint) },
-                allow_nil: true
-
       # @!attribute [rw] type
       #   String representing the type of inspection. Must be (initial,
       #   routine, followup, complaint).
       #   @return [String]
       attr_accessor :type
+      validates :type,
+                inclusion: { in: %w(initial routine followup complaint) },
+                allow_nil: true
 
       # @return [String]
       def to_s

data/lib/eaternet/lives_1_0/legend.rb

@@ -2,14 +2,40 @@ require 'eaternet/validated_object'
 
 module Eaternet
   module Lives_1_0
+    # Legends are mappings from score ranges to human-readable descriptions of
+    # those scores. Municipalities can use these to communicate the way scores
+    # are traditionally presented. For example, 0-60 may map to ‘Fail’ or 95-100
+    # may map to ‘A+’. The provided ranges in {#minimum_score} and
+    # {#maximum_score} must cover the entire 0-100 span without overlap. For
+    # scores at the edge of two ranges, the greater range will be used. For
+    # example, if 80-90 is a ‘B’ and 90-100 is an ‘A’, a score of 90 would be an
+    # ‘A’. These are optional.
+    #
+    # @see LegendGroup Lives_1_0::LegendGroup, which enforces the 0–100 span and
+    #   checks for overlap.
+    # @see http://www.yelp.com/healthscores#legend LIVES / Legend specification
     class Legend < ValidatedObject
-      attr_accessor :minimum_score, :maximum_score, :description
+      # Minimum score that can be classified with this description.
+      #
+      # @required Yes
+      # @return [Integer]
+      attr_accessor :minimum_score
+      validates :minimum_score, inclusion: { in: (0..100) }
 
-      validates :minimum_score, :maximum_score,
-                inclusion: { in: (0..100) }
-      validates :description,
-                presence: true,
-                type: String
+      # Maximum score that can be classified with this description.
+      #
+      # @required Yes
+      # @return [Integer]
+      attr_accessor :maximum_score
+      validates :maximum_score, inclusion: { in: (0..100) }
+
+      # Formatted version of the score in the format typically presented by the
+      # municipality. For example ‘A’ or ‘Pass’.
+      #
+      # @required Yes
+      # @return [String]
+      attr_accessor :description
+      validates :description, presence: true, type: String
     end
   end
 end

data/lib/eaternet/lives_1_0/legend_group.rb

@@ -3,9 +3,16 @@ require 'eaternet/validated_object'
 
 module Eaternet
   module Lives_1_0
-    # A container for all the Legends in the data set. Performs
-    # validation on the whole set of Legends to ensure they cover
-    # the entire range of scores and do not overlap, as spec'd.
+    # A container for all the Legends in the data set. Performs validation on
+    # the whole set of Legends to ensure they cover the entire range of scores
+    # and do not overlap, as specified:
+    #
+    # "The provided ranges [...] must cover the entire 0–100 span without
+    # overlap. For scores at the edge of two ranges, the greater range will be
+    # used."
+    #
+    # @see http://www.yelp.com/healthscores#legend LIVES / Score Legend
+    #   specification
     class LegendGroup < ValidatedObject
       attr_accessor :legends
 
@@ -13,6 +20,8 @@ module Eaternet
       #
       #   1. Are of the class, Legend
       #   2. Cover the range of scores from 0-100 without overlap
+      #
+      # @todo: Refactor
       class ComprehensiveValidator < ActiveModel::EachValidator
         def validate_each(record, attribute, legends)
           scores = (0..100).to_a

data/lib/eaternet/lives_1_0/violation.rb

@@ -2,7 +2,9 @@ require 'eaternet/validated_object'
 
 module Eaternet
   module Lives_1_0
+    # @todo Document
     # @see http://www.yelp.com/healthscores#violations LIVES / Violations
+    #   specification
     class Violation < ValidatedObject
       attr_accessor :business_id, :date, :code, :description
 

data/lib/eaternet/validated_object.rb

@@ -8,7 +8,7 @@ module Eaternet
   # to create self-validating Plain Old Ruby objects. This is especially useful for
   # data validation when importing from CSV.
   #
-  # @example
+  # @example Writing a self-validating object
   #   class Dog < Eaternet::ValidatedObject
   #     attr_accessor :name, :birthday
   #
@@ -16,19 +16,22 @@ module Eaternet
   #     validates :birthday, type: Date, allow_nil: true
   #   end
   #
+  # @example Instantiating and automatically validating
   #   # The dog1 instance is validated at the end of instantiation. Here, it succeeds
-  #   # without exception:
+  #   # without exception.
   #   dog1 = Dog.new do |d|
   #     d.name = 'Spot'
   #   end
   #
-  #   puts dog1.valid?  # => true
+  #   # We can also explicitly test for validity
+  #   dog1.valid?  # => true
   #
   #   dog1.birthday = Date.new(2015, 1, 23)
-  #   puts dog1.valid?  # => true
+  #   dog1.valid?  # => true
   #
+  # @example Making an instance invalid
   #   dog1.birthday = '2015-01-23'
-  #   puts dog1.valid?  # => false
+  #   dog1.valid?  # => false
   #   dog1.check_validations!  # => ArgumentError: birthday is not of class Date
   #
   # @see Eaternet::ValidatedObject::TypeValidator
@@ -55,15 +58,16 @@ module Eaternet
       fail ArgumentError, errors.messages.inspect if invalid?
     end
 
-    # Ensure an object is a certain class. This is an example of a custom
-    # validator. It's here as a nested class for easy access by subclasses.
+    # A custom validator which ensures an object is a certain class.
+    # It's here as a nested class in {ValidatedObject} for easy access by subclasses.
     #
-    # @example
+    # @example Ensure that weight is a floating point number
     #   class Dog < ValidatedObject
     #     attr_accessor :weight
     #     validates :weight, type: Float
     #   end
     class TypeValidator < ActiveModel::EachValidator
+      # @return [nil]
       def validate_each(record, attribute, value)
         return if value.class == options[:with]
 

data/lib/eaternet/version.rb

@@ -1,3 +1,3 @@
 module Eaternet
-  VERSION = '0.3.4'
+  VERSION = '0.3.5'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eaternet
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
 platform: ruby
 authors:
 - Robb Shecter
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-18 00:00:00.000000000 Z
+date: 2015-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -175,6 +175,7 @@ files:
 - ".gitignore"
 - ".inch.yml"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - Guardfile
 - LICENSE.txt