five-star 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 408c38478386dfd30afac94401ef9f609a4102c1
-  data.tar.gz: ce73a704c2f2ef208f45d5ab95759e05f30f19be
+  metadata.gz: f0ec61a85ec090995b6030203a9b8808e85ff27e
+  data.tar.gz: a21d6768ecb083c34b4b103d78100f2095d726dc
 SHA512:
-  metadata.gz: f8fb0c43adac3af9fd729f1326ab1e3b8dfc0e18ea1e72f4a7065582cdfc5ece24ca2b7b7c5d867380ca6919d06ab1d80a8f3037ab973b1fcee873962c9af6ee
-  data.tar.gz: f988375e92f8224ae05b7d5956da34134fe47080ea74d5d1510631017760ad8e184e3bd81d57e17fc2682fb3a272aee7b80e3110ca57fd7642f1238715070355
+  metadata.gz: ca8a6fdb9c2f2fd00d25ea31ca507fafa6cd69c0c9eb3bbe7d3509f368b67a35329012be76909f56a71defb91be16a3d35358eed729e8623a7d586466f810aa2
+  data.tar.gz: b1734c47ace30591629843cc41dfda108c2671e13cf2c15831972659db6b55025a5c5f74b869e76dfd815f4438a539e250bf1cf7bc9d202799836d054d4595f1

data/README.md

@@ -1,21 +1,19 @@
 # FiveStar
-### A generic rating library :star:
 
 [![Build Status](https://travis-ci.org/rob-murray/five-star.svg?branch=master)](https://travis-ci.org/rob-murray/five-star)
-[![Code Climate](https://codeclimate.com/github/rob-murray/five-star.png)](https://codeclimate.com/github/rob-murray/five-star)
-[![Coverage Status](https://coveralls.io/repos/rob-murray/five-star/badge.png)](https://coveralls.io/r/rob-murray/five-star)
-[![Dependency Status](https://gemnasium.com/rob-murray/five-star.svg)](https://gemnasium.com/rob-murray/five-star)
+[![Code Climate](https://codeclimate.com/github/rob-murray/five-star.svg)](https://codeclimate.com/github/rob-murray/five-star)
+[![Coverage Status](https://coveralls.io/repos/rob-murray/five-star/badge.svg?branch=master&service=github)](https://coveralls.io/github/rob-murray/five-star?branch=master)
 [![Gem Version](https://badge.fury.io/rb/five-star.svg)](http://badge.fury.io/rb/five-star)
 
-:star: **FiveStar** :star: is a library to build a rating system - it allows you to rate *something* in your domain by classification or criteria you define. This library gives you the structure to rate your object with as many of these different classifications as you like with the overall rating as a weighted average.
 
-This uses Plain Old Ruby Objects so can be used in any project. Implement or use whatever persistence layer you want.
+:star: **FiveStar** :star: is a library to build a rating system - it allows you to rate *something* in your domain by various classification or criteria you define. This library gives you the structure to rate your object with as many of these different classifications as you like with the overall rating calculated from the weighted average.
+
+This uses *Plain Old Ruby Objects* so can be used in any project.
 
-> Not sure if this is a gem or just a code design pattern :/
 
 ## Example
 
-Say you implemented a film rating system, you have lots of `Film` objects each with different attributes and you would like to show an overall rating for each film based on classifications below.
+Say you implemented a film rating system, you have lots of `Film` objects each with different attributes and you would like to show an overall rating for each film based on classifications below. You might give the amount of swearing in the film slightly less weighting that the amount of sex and violence.
 
 * Gore - Amount of blood in the movie - weighting: 40%
 * Sex - Number of references to sex in the movie - weighting: 40%
@@ -29,18 +27,32 @@ class Film
 
   rate_with GoreRater, SwearingRater, SexRater
 
-  # rest of you implementation
+  # rest of your implementation
+  def blood_spilt
+    # ...
+  end
+
+  def number_of_swear_words
+    # ...
+  end
 end
 
 class GoreRater < FiveStar.base_rater
   rating_weight 0.4
 
   def description
-    "This Film was rated #{rating} for gore"
+    "The film #{film.title} was rated #{rating} for gore"
   end
 
   def rating
-    # count the pints of blood spilt in the film
+    # count the pints of blood spilt in the film and return a rating
+    if film.blood_spilt == :a_lot
+      10
+    elsif film.blood_spilt == :a_little
+      5
+    else
+      0
+    end
   end
 end
 
@@ -48,17 +60,18 @@ class SwearingRater < FiveStar.base_rater
   rating_weight 0.2
 
   def description
-    "This Film was has #{number_of_swear_words} and was rated at #{rating}"
+    "The film #{film.title} has #{film.number_of_swear_words} and was rated at #{rating}"
   end
 
   def rating
-    # count the number of swear words in the film
+    # count the number of swear words in the film & convert to our rating scale
+    linear_conversion(film.number_of_swear_words)
   end
 end
 
 film = Film.new
 film.rating # => 6
-film.rating_descriptions # => ["This Film was rated 8 for gore", ...]
+film.rating_descriptions # => ["The film Alien was rated 8 for gore", ...]
 
 ```
 
@@ -81,21 +94,23 @@ Or install it yourself as:
 
 ## Usage
 
-There are two components required, the thing being rated and how it is rated - the thing you want rated is defined as being rateable and you can have one or more "raters" to give it a rating. You must implement your these raters and provide the classes to the item being rated, this library takes care of the rest.
+There are two components required, the thing being rated and how it is rated - the thing you want rated is defined as being rateable and you can have one or more rating classes to give it a rating. You must implement your these raters and provide the classes to the item being rated, this library takes care of the rest.
+
+* `rateable` - This is the object that can be rated -  this is your domain model that has various attributes that you need rated.
+* `rater` - A class that knows how to give a rating to the object being rated based on classification of the rateable's attributes.
 
-* `Rateable` - This is the object that can be rated based on
-* `Rater` - A class that knows how to give a rating to the object being rated
+Each `rater` must return a rating within the scale given and a weighting which will be used to calculate the overall rating.
 
-Each `Rater` must return a rating within the scale given and a weighting which will be used to calculate the overall rating.
+The default rating scale used is 0 - 10 as floating point numbers although this can be overriden and customised.
 
-The current rating scale used is 0 - 10 as floating point numbers that can be rounded as you require.
+The rating calculation will take the rating value from each rater along with the weighting to calculate the overall average rating.
 
 ### Rateable
 
 This module when included gives the object the following interface on the instance.
 
-* `rating` - `[Float]` -  The overall rating calculated
-* `rating_descriptions` - `[Array]` - A list of the description from each rater class
+* `rating` - `@return [Float]` -  The overall rating calculated for the rateable object.
+* `rating_descriptions` - `@return [Array]` - A list of description from each raters. This is delegated to the rater.
 
 The classes used to rate the object can be specified using the class method `rate_with(*class_names)` and passing in one or more rating classes.
 
@@ -104,29 +119,31 @@ class Film
   include FiveStar.rateable
 
   rate_with GoreRater, SwearingRater, SexRater
-...
+  # ...
+end
 
 film = Film.new
 film.rating # => 6
-film.rating_descriptions # => ["This Film was rated 8 for gore", ...]
+film.rating_descriptions # => ["The film Alien was rated 8 for gore", ...]
 ```
 
 ### Rater
 
 You can create your own rating classes however you like but they should respond to the following methods;
 
-* `rating` - `[Float]` - The rating for the object being rated
-* `description` - `[String]` - A description of the rating, eg reason it was rated at that value
-* `weighting` - `[Float]` - The weighting for this classification
+* `build` - `@param [Rateable], @return [instance of rater]` - Create a new instance of rater with rateable as argument.
+* `rating` - `@return [Float]` - The rating for the object being rated. Calculate this by your own classification.
+* `description` - `@return [String]` - A description of the rating, eg reason it was rated at that value.
+* `weighting` - `@return [Float]` - The weighting for this classification. Withing range 0.0 - 1.0
 
-The **FiveStar** will call `build` method on the `Rater` with the argument of the instance of class being rated which should do any setup and return an instance of the rater.
+The **FiveStar** library will call the `build` method on the `Rater` with the argument of the instance of class being rated which should do any setup and return an instance of the rater.
 
-For simplicity you can subclass `FiveStar.base_rater` and get the following for free.
+For simplicity you can subclass `FiveStar.base_rater` and get the following for free. If the above methods are not overriden then the default implementation will be used.
 
-* `rating_weight` - Class method to set the weighting for this rater
-* `rateable` - Instance method referencing the object being rated
-* `min_rating` - Instance method returning the minimum rating value
-* `max_rating` - Instance method returning the maximum rating value
+* `rating_weight` - `@param [Float]` - Class method to set the weighting for this rater
+* `rateable` - `@return [Rateable]` - Instance method referencing the object being rated
+* `min_rating` - `@return [Float]` - Instance method returning the minimum rating value
+* `max_rating` - `@return [Float]` - Instance method returning the maximum rating value
 
 For example a basic version could be something like this;
 
@@ -135,7 +152,7 @@ class GoreRater < FiveStar.base_rater
   rating_weight 0.4
 
   def description
-    "This Film was rated #{rating} for gore"
+    "The film #{film.title} has #{film.number_of_swear_words} and was rated at #{rating}"
   end
 
   def rating
@@ -146,9 +163,9 @@ end
 
 ### Rating calculation
 
-The calculation used will be a weighted average based on each rating and the weighting. If weighting is not required then all will be use the default value and therefore be weighted the same which is just a normal mean average calculation.
+The calculation used will be a weighted average based on each rating and the weighting defined in that class. If weighting is not required then all will be use the default value (of 1.0) and therefore be weighted the same, this being just a normal mean average calculation.
 
-The minimum rating is 0.0 and the maximum is 10.0
+The default rating scale used is 0 - 10 as floating point numbers although this can be overriden and customised.
 
 
 ## Development

data/five-star.gemspec

@@ -27,4 +27,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pry"
   spec.add_development_dependency "coveralls"
   spec.add_development_dependency "codeclimate-test-reporter"
+  spec.add_development_dependency "byebug" if RUBY_PLATFORM != 'java'
 end

data/lib/five-star.rb

@@ -3,12 +3,59 @@ require "five-star/base_rater"
 require "five-star/rateable"
 require "five-star/rating_calculator"
 
+# Base module for library interface
 module FiveStar
   class << self
+    # Include this in your class that can be rated - this is your domain model
+    #   object that has various attributes that you need rated.
+    # Being +rateable+ is defined as an object that has attributes on which a
+    #   rating can be calculated based on varying attributes of that model.
+    #
+    # This adds the public class and instance methods from the Rateable module.
+    # See FiveStar::Rateable
+    #
+    # @example
+    #   class Film
+    #     include FiveStar.rateable
+    #
+    #     rate_with GoreRater, SwearingRater, SexRater
+    #     # ...
+    #   end
+    #
+    # @return [Class]
+    #
+    # @api public
     def rateable
       Rateable
     end
 
+    # The base class of a class that gives a rating and weighting to something
+    #   that is rateable. See FiveStar.rateable.
+    #
+    # This implements the interface necessary to calculate a rating for the
+    #   rateable instance. At a minium this must be +build+, +rating+,
+    #   +description+ and +weighting+.
+    #
+    # The method +build+ *will* be called on each class with the argument of
+    #   the instance being rated.
+    # See FiveStar::BaseRater
+    #
+    # @example
+    #   class GoreRater < FiveStar.base_rater
+    #     rating_weight 0.4
+    #
+    #     def description
+    #       "The Film #{film.title} has #{film.number_of_swear_words} and was rated at #{rating}"
+    #     end
+    #
+    #     def rating
+    #       # calculate rating somehow
+    #     end
+    #   end
+    #
+    # @return [Class]
+    #
+    # @api public
     def base_rater
       BaseRater
     end

data/lib/five-star/base_rater.rb

@@ -1,29 +1,123 @@
 module FiveStar
+  # Base implementation of a class to give a rating, weighting and description
+  #   to a +rateable+ instance.
+  #
+  # Default implementation is defined below, users should override methods
+  #   with their own implementation.
   class BaseRater
+    # Called to build a new instance of the rater with the given object
+    #   being rated.
+    #
+    # @param [Object] rateable
+    #   the instance of the Object being rated
+    #
+    # @return [Object] the instance created ready to rate
+    #
+    # @api public
     def self.build(rateable)
       new(rateable)
     end
 
+    # Set the weighting for this rating classifcation class. This can be any
+    #   valid floating point number at present, the weighting system is up to
+    #   the user to ensure correct.
+    #
+    # @example
+    #   class GoreRater < FiveStar.base_rater
+    #     rating_weight 0.4
+    #     # ...
+    #   end
+    #
+    # @param [Float] weighting
+    #   the weighting value
+    #
+    # @return [undefined]
+    #
+    # @api public
     def self.rating_weight(weighting)
       @weighting = weighting
     end
 
+    # Return the weighting value for this rating classifcation class.
+    #
+    # @return [Float]
+    #   the weighting value
+    #
+    # @api public
     def self.weighting
       @weighting ||= 1.0
     end
 
+    # Create a new instance of rater
+    #
+    # @param [Object] rateable
+    #   the instance of the Object being rated
+    #
+    # @api private
     def initialize(rateable)
       @rateable = rateable
     end
 
+    # Return the rating description for the rater given to the `rateable`
+    #   object.
+    # Override to customise this message.
+    #
+    # @example
+    #   class GoreRater < FiveStar.base_rater
+    #     rating_weight 0.4
+    #
+    #     def description
+    #       "The film #{film.title} has #{film.number_of_swear_words} and was rated at #{rating}"
+    #     end
+    #   end
+    #
+    #   rater.description # => "The film Alien was rated 8 for gore"
+    #
+    # @return [String] the description
+    #
+    # @api public
     def description
-      "#{self.class} rated #{rateable.class} at #{rating} with weighting of #{weighting}"
+      "#{self.class} rated #{rateable_name} at #{rating} with weighting of #{weighting}"
     end
 
+    # Return the rating for the rater given to the `rateable` object.
+    # Override this method to perform your own calculation for the rating based
+    #   on your own criteria. If this is an expensive operation then the result
+    #   should be cached as this method *can* be called more than once, for
+    #   example by the +description+ method.
+    #
+    # @example
+    #   class GoreRater < FiveStar.base_rater
+    #     rating_weight 0.4
+    #
+    #     def rating
+    #       # count the pints of blood spilt in the film and return a rating
+    #       if film.blood_spilt == :a_lot
+    #         10
+    #       elsif film.blood_spilt == :a_little
+    #         5
+    #       else
+    #         0
+    #       end
+    #     end
+    #   end
+    #
+    #   rater.rating # => 6
+    #
+    # @return [Float] the rating value
+    #   defaults to 0 unless overridden
+    #
+    # @api public
     def rating
       0
     end
 
+    # Return the weighting value for this rating classifcation class.
+    #
+    # @return [Float]
+    #   the weighting value
+    #
+    # @api public
     def weighting
       self.class.weighting
     end
@@ -32,12 +126,38 @@ module FiveStar
 
     attr_reader :rateable
 
+    # Return the maximum weighting value for this rating classifcation class.
+    #
+    # Override if required - this should be the same for each rater class.
+    #
+    # @return [Fixnum]
+    #   the maximum rating value.
+    #
+    # @api protected
     def max_rating
       10
     end
 
+    # Return the minimum weighting value for this rating classifcation class.
+    #
+    # Override if required - this should be the same for each rater class.
+    #
+    # @return [Fixnum]
+    #   the minimum rating value.
+    #
+    # @api protected
     def min_rating
       0
     end
+
+    # Return the name of the given rateable instance.
+    #
+    # @return [String]
+    #   the name of the object being rated.
+    #
+    # @api protected
+    def rateable_name
+      rateable.name
+    end
   end
 end

data/lib/five-star/rateable.rb

@@ -1,29 +1,105 @@
 module FiveStar
+  # A module to be included to enhance an object with the interface below
   module Rateable
+    # Extends base class or a module with Rateable methods
+    #
+    # @param [Object] object
+    #   the object to mix in this +Rateable+ module
+    #
+    # @return [undefined]
+    #
+    # @api private
     def self.included(base)
       base.extend(ClassMethods)
     end
 
     module ClassMethods
+      # Set which rating classes will be used to rate the object
+      #  using this module.
+      # Each class must implement the rater methods, see FiveStar::BaseRater
+      #
+      # @example
+      #    class Film
+      #      include FiveStar.rateable
+      #
+      #      rate_with GoreRater, SwearingRater, SexRater
+      #      # ...
+      #    end
+      #
+      # @param [Class] *klasses
+      #   constants referencing classes to rate object included with
+      #
+      # @return [undefined]
+      #
+      # @see FiveStar.rateable
+      #
+      # @api public
       def rate_with(*klasses)
         @rating_klasses = Array(klasses)
       end
 
+      # Define which rating classes will be used to rate the object
+      #  using this module.
+      #
+      # @return [Array] list of classes to rate with
+      #
+      # @see FiveStar.rateable
+      #
+      # @api private
       def rating_klasses
         @rating_klasses ||= []
       end
     end
 
+    # Return the rating given to the `rateable` object by calculating based on
+    #   set raters and their configuration.
+    #
+    # @example
+    #    film = Film.new
+    #    film.rating # => 6
+    #
+    # @return [Float] rating calculated by set raters for the object
+    #
+    # @api public
     def rating
       rating_calculator.rate(raters)
     end
 
+    # Return the rating description for each rater given to the `rateable`
+    #   object.
+    # These are returned in the order in which the rating classes were
+    #   defined in `rate_with`.
+    #
+    # @example
+    #    film = Film.new
+    #    film.rating_descriptions # => ["The film Alien was rated 8 for gore", ...]
+    #
+    # @return [Array] list of descriptions from each rater
+    #
+    # @api public
     def rating_descriptions
       raters.map { |rater| rater.description }
     end
 
+    # The name of the object that is rateable. This may be used by raters
+    #   when generating descriptions.
+    # This can be overridden to provide a better response, otherwise is the class
+    #   name.
+    #
+    # @return [String] name of the class
+    #
+    # @api public
+    def name
+      self.class.name
+    end
+
     protected
 
+    # The instance that included this module
+    #
+    # @return [Object] self
+    #
+    # @api protected
     def rateable
       self
     end

data/lib/five-star/rating_calculator.rb

@@ -1,4 +1,7 @@
 module FiveStar
+  # Calculate overall rating for the rateable object from each rater.
+  #   Each instance must implement `rating` and `weighting`.
+  # @api private
   class RatingCalculator
     def self.rate(raters)
       new(raters).calculate_rating
@@ -8,17 +11,27 @@ module FiveStar
       @raters = raters
     end
 
+    # Calculate the overall weighting from each rating class
+    #
+    # @return [Float] the calculated rating
+    #
+    # @api private
     def calculate_rating
       return 0 unless raters.any?
 
-      sum_total = raters.map { |rater| rater.rating * rater.weighting }.inject(&:+)
-      weights_total = raters.map(&:weighting).inject(&:+)
-
       sum_total / weights_total.to_f
     end
 
     private
 
     attr_reader :raters
+
+    def sum_total
+      raters.map { |rater| rater.rating * rater.weighting }.inject(&:+)
+    end
+
+    def weights_total
+      raters.map(&:weighting).inject(&:+)
+    end
   end
 end

data/lib/five-star/version.rb

@@ -1,3 +1,3 @@
 module FiveStar
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: five-star
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Rob Murray
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-11-14 00:00:00.000000000 Z
+date: 2015-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -94,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Rating system for your Ruby objects; Rate an object with one or more
   rating classifications.
 email:
@@ -108,7 +122,6 @@ files:
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE
-- LICENSE.txt
 - README.md
 - Rakefile
 - bin/console

data/LICENSE.txt

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2015 Rob Murray
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.