stoplight 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9619bee3f557017bc7b877349a5a2b5985e535ce
-  data.tar.gz: 5dec1f7bce5d8373cea3747e8dc587e0795e19c2
+  metadata.gz: bcc53c7687a3a7fc307685f81463b7a97aec96bd
+  data.tar.gz: 7fe4bfe9357b1a52ffad84dbba77decbb8875979
 SHA512:
-  metadata.gz: 9f12b3bbf04f13f74c91ef78c3c85909a720e15003808609bb9d06e5886643a52d17a83e37263e1dc10666dd286f8e3fdb2784652b553b35eafc47f920368d76
-  data.tar.gz: 4437c4f2618ac10732bdccd600699590780d1d162d8f6523206115a283d0d616e389a58fbe7ea56c07010f087768ed9918fbd2f092177e9944ea33fc6b142bc0
+  metadata.gz: d2461d125e6b721bb12d38eddfa0047e823899febb818f7276006cea9a8da70cef5215efe77b6017b0fe3a3b92c389e0927306b385cdf347a3903d048fed989b
+  data.tar.gz: bd7939dd6723a2a405865aa756b9cc4d903b00931eff7796d3276ea98aa3d4b139b23809cd726ee3a17b446ca59a976a0095645283386d10ac2e65f1390c5290

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 This project uses [Semantic Versioning][1].
 
+## v0.5.2 (2014-11-19)
+
+- Created a convenience function for creating stoplights.
+- Created a `VERSION` constant.
+- Added YARD type documentation for public methods.
+
 ## v0.5.1 (2014-11-19)
 
 - Fixed a logic bug that incorrectly determined red lights to be yellow.

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Cameron Desautels, Taylor Fausak & Justin Steffy
+Copyright (c) 2015 Cameron Desautels, Taylor Fausak & Justin Steffy
 
 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

data/README.md

@@ -1,17 +1,39 @@
-# [Stoplight][1]
-
-[![Gem version][2]][3]
-[![Build status][4]][5]
-[![Coverage status][6]][7]
-[![Quality status][8]][9]
-[![Dependency status][10]][11]
-
-<img align="right" alt="Stoplight icon" src="https://i.imgur.com/tiuOfY9.png">
-
-Traffic control for code. An implementation of the circuit breaker pattern in
-Ruby.
-
-Check out [stoplight-admin][12] for controlling your stoplights.
+<p align="center">
+  <img alt="Stoplight" src="stoplight.png">
+</p>
+
+<h1 align="center">
+  <a href="https://github.com/orgsync/stoplight">
+    Stoplight
+  </a>
+</h1>
+
+<p align="center">
+  Stoplight is traffic control for code. It's an implementation of
+  the circuit breaker pattern in Ruby.
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/stoplight">
+    <img alt="" src="https://img.shields.io/gem/v/stoplight.svg">
+  </a>
+  <a href="https://travis-ci.org/orgsync/stoplight">
+    <img alt="" src="https://img.shields.io/travis/orgsync/stoplight/master.svg">
+  </a>
+  <a href="https://coveralls.io/r/orgsync/stoplight">
+    <img alt="" src="https://img.shields.io/coveralls/orgsync/stoplight/master.svg">
+  </a>
+  <a href="https://codeclimate.com/github/orgsync/stoplight">
+    <img alt="" src="https://img.shields.io/codeclimate/github/orgsync/stoplight.svg">
+  </a>
+  <a href="https://gemnasium.com/orgsync/stoplight">
+    <img alt="" src="https://img.shields.io/gemnasium/orgsync/stoplight.svg">
+  </a>
+</p>
+
+<hr>
+
+Check out [stoplight-admin][] for controlling your stoplights.
 
 - [Installation](#installation)
 - [Setup](#setup)
@@ -33,13 +55,13 @@ Check out [stoplight-admin][12] for controlling your stoplights.
 Add it to your Gemfile:
 
 ``` rb
-gem 'stoplight', '~> 0.5.1'
+gem 'stoplight', '~> 0.5.2'
 ```
 
 Or install it manually:
 
 ``` sh
-$ gem install stoplight
+$ gem install stoplight --version '~> 0.5.2'
 ```
 
 ## Setup
@@ -48,58 +70,60 @@ $ gem install stoplight
 
 Stoplight uses an in-memory data store out of the box.
 
-``` irb
->> require 'stoplight'
-=> true
->> Stoplight::Light.default_data_store
-=> #<Stoplight::DataStore::Memory:...>
+``` rb
+require 'stoplight'
+# => true
+Stoplight::Light.default_data_store
+# => #<Stoplight::DataStore::Memory:...>
 ```
 
-If you want to use a persistent data store, you'll have to set it up. Currently
-the only supported persistent data store is Redis. Make sure you have [the Redis
-gem][13] installed before configuring Stoplight.
-
-``` irb
->> require 'redis'
-=> true
->> redis = Redis.new
-=> #<Redis client ...>
->> data_store = Stoplight::DataStore::Redis.new(redis)
-=> #<Stoplight::DataStore::Redis:...>
->> Stoplight::Light.default_data_store = data_store
-=> #<Stoplight::DataStore::Redis:...>
+If you want to use a persistent data store, you'll have to set it
+up. Currently the only supported persistent data store is Redis.
+Make sure you have [the Redis gem][] installed before configuring
+Stoplight.
+
+``` rb
+require 'redis'
+# => true
+redis = Redis.new
+# => #<Redis client ...>
+data_store = Stoplight::DataStore::Redis.new(redis)
+# => #<Stoplight::DataStore::Redis:...>
+Stoplight::Light.default_data_store = data_store
+# => #<Stoplight::DataStore::Redis:...>
 ```
 
 ### Notifiers
 
 Stoplight sends notifications to standard error by default.
 
-``` irb
->> Stoplight::Light.default_notifiers
-=> [#<Stoplight::Notifier::IO:...>]
+``` rb
+Stoplight::Light.default_notifiers
+# => [#<Stoplight::Notifier::IO:...>]
 ```
 
-If you want to send notifications elsewhere, you'll have to set them up.
-Currently the only other supported notifier is HipChat. Make sure you have [the
-HipChat gem][14] installed before configuring Stoplight.
-
-``` irb
->> require 'hipchat'
-=> true
->> hip_chat = HipChat::Client.new('token')
-=> #<HipChat::Client:...>
->> notifier = Stoplight::Notifier::HipChat.new(hip_chat, 'room')
-=> #<Stoplight::Notifier::HipChat:...>
->> Stoplight::Light.default_notifiers += [notifier]
-=> [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::HipChat:...>]
+If you want to send notifications elsewhere, you'll have to set
+them up. Currently the only other supported notifier is HipChat.
+Make sure you have [the HipChat gem][] installed before configuring
+Stoplight.
+
+``` rb
+require 'hipchat'
+# => true
+hip_chat = HipChat::Client.new('token')
+# => #<HipChat::Client:...>
+notifier = Stoplight::Notifier::HipChat.new(hip_chat, 'room')
+# => #<Stoplight::Notifier::HipChat:...>
+Stoplight::Light.default_notifiers += [notifier]
+# => [#<Stoplight::Notifier::IO:...>, #<Stoplight::Notifier::HipChat:...>]
 ```
 
 ### Rails
 
-Stoplight is designed to work seamlessly with Rails. If you want to use the
-in-memory data store, you don't need to do anything special. If you want to use
-a persistent data store, you'll need to configure it. Create an initializer for
-Stoplight:
+Stoplight is designed to work seamlessly with Rails. If you want
+to use the in-memory data store, you don't need to do anything
+special. If you want to use a persistent data store, you'll need
+to configure it. Create an initializer for Stoplight:
 
 ``` rb
 # config/initializers/stoplight.rb
@@ -112,150 +136,152 @@ Stoplight::Light.default_notifiers += [Stoplight::Notifier::HipChat.new(...)]
 
 To get started, create a stoplight:
 
-``` irb
->> light = Stoplight::Light.new('example-1') { 22.0 / 7 }
-=> #<Stoplight::Light:...>
+``` rb
+light = Stoplight('example-1') { 22.0 / 7 }
+# => #<Stoplight::Light:...>
 ```
 
-Then you can run it and it will return the result of calling the block. This is
-the green state.
+Then you can run it and it will return the result of calling the
+block. This is the green state.
 
-``` irb
->> light.run
-=> 3.142857142857143
->> light.color
-=> "green"
+``` rb
+light.run
+# => 3.142857142857143
+light.color
+# => "green"
 ```
 
-If everything goes well, you shouldn't even be able to tell that you're using a
-stoplight. That's not very interesting though. Let's create a failing stoplight:
+If everything goes well, you shouldn't even be able to tell that
+you're using a stoplight. That's not very interesting though. Let's
+create a failing stoplight:
 
-``` irb
->> light = Stoplight::Light.new('example-2') { 1 / 0 }
-=> #<Stoplight::Light:...>
+``` rb
+light = Stoplight('example-2') { 1 / 0 }
+# => #<Stoplight::Light:...>
 ```
 
-Now when you run it, the error will be recorded and passed through. After
-running it a few times, the stoplight will stop trying and fail fast. This is
-the red state.
-
-``` irb
->> light.run
-ZeroDivisionError: divided by 0
->> light.run
-ZeroDivisionError: divided by 0
->> light.run
-Switching example-2 from green to red because ZeroDivisionError divided by 0
-ZeroDivisionError: divided by 0
->> light.run
-Stoplight::Error::RedLight: example-2
->> light.color
-=> "red"
+Now when you run it, the error will be recorded and passed through.
+After running it a few times, the stoplight will stop trying and
+fail fast. This is the red state.
+
+``` rb
+light.run
+# ZeroDivisionError: divided by 0
+light.run
+# ZeroDivisionError: divided by 0
+light.run
+# Switching example-2 from green to red because ZeroDivisionError divided by 0
+# ZeroDivisionError: divided by 0
+light.run
+# Stoplight::Error::RedLight: example-2
+light.color
+# => "red"
 ```
 
-When the stoplight changes from green to red, it will notify every configured
-notifier.
+When the stoplight changes from green to red, it will notify every
+configured notifier.
 
 ### Custom errors
 
-Some errors shouldn't cause your stoplight to move into the red state. Usually
-these are handled elsewhere in your stack and don't represent real failures. A
-good example is `ActiveRecord::RecordNotFound`.
-
-``` irb
->> light = Stoplight::Light.new('example-3') { User.find(123) }.
-..   with_allowed_errors([ActiveRecord::RecordNotFound])
-=> #<Stoplight::Light:...>
->> light.run
-ActiveRecord::RecordNotFound: Couldn't find User with ID=123
->> light.run
-ActiveRecord::RecordNotFound: Couldn't find User with ID=123
->> light.run
-ActiveRecord::RecordNotFound: Couldn't find User with ID=123
->> light.color
-=> "green"
+Some errors shouldn't cause your stoplight to move into the red
+state. Usually these are handled elsewhere in your stack and don't
+represent real failures. A good example is `ActiveRecord::RecordNotFound`.
+
+``` rb
+light = Stoplight('example-3') { User.find(123) }
+  .with_allowed_errors([ActiveRecord::RecordNotFound])
+# => #<Stoplight::Light:...>
+light.run
+# ActiveRecord::RecordNotFound: Couldn't find User with ID=123
+light.run
+# ActiveRecord::RecordNotFound: Couldn't find User with ID=123
+light.run
+# ActiveRecord::RecordNotFound: Couldn't find User with ID=123
+light.color
+# => "green"
 ```
 
 ### Custom fallback
 
-By default, stoplights will re-raise errors when they're green. When they're
-red, they'll raise a `Stoplight::Error::RedLight` error. You can provide a
-fallback that will be called in both of these cases. It will be passed the error
-if the light was green.
-
-``` irb
->> light = Stoplight::Light.new('example-4') { 1 / 0 }.
-..   with_fallback { |e| p e; 'default' }
-=> #<Stoplight::Light:..>
->> light.run
-#<ZeroDivisionError: divided by 0>
-=> "default"
->> light.run
-#<ZeroDivisionError: divided by 0>
-=> "default"
->> light.run
-Switching example-4 from green to red because ZeroDivisionError divided by 0
-#<ZeroDivisionError: divided by 0>
-=> "default"
->> light.run
-nil
-=> "default"
+By default, stoplights will re-raise errors when they're green.
+When they're red, they'll raise a `Stoplight::Error::RedLight`
+error. You can provide a fallback that will be called in both of
+these cases. It will be passed the error if the light was green.
+
+``` rb
+light = Stoplight('example-4') { 1 / 0 }
+  .with_fallback { |e| p e; 'default' }
+# => #<Stoplight::Light:..>
+light.run
+# #<ZeroDivisionError: divided by 0>
+# => "default"
+light.run
+# #<ZeroDivisionError: divided by 0>
+# => "default"
+light.run
+# Switching example-4 from green to red because ZeroDivisionError divided by 0
+# #<ZeroDivisionError: divided by 0>
+# => "default"
+light.run
+# nil
+# => "default"
 ```
 
 ### Custom threshold
 
-Some bits of code might be allowed to fail more or less frequently than others.
-You can configure this by setting a custom threshold in seconds.
-
-``` irb
->> light = Stoplight::Light.new('example-5') { fail }.
-..   with_threshold(1)
-=> #<Stoplight::Light:...>
->> light.run
-Switching example-5 from green to red because RuntimeError
-RuntimeError:
->> light.run
-Stoplight::Error::RedLight: example-5
+Some bits of code might be allowed to fail more or less frequently
+than others. You can configure this by setting a custom threshold
+in seconds.
+
+``` rb
+light = Stoplight('example-5') { fail }
+  .with_threshold(1)
+# => #<Stoplight::Light:...>
+light.run
+# Switching example-5 from green to red because RuntimeError
+# RuntimeError:
+light.run
+# Stoplight::Error::RedLight: example-5
 ```
 
 ### Custom timeout
 
-Stoplights will automatically attempt to recover after a certain amount of time.
-A light in the red state for longer than the timeout will transition to the
-yellow state. This timeout is customizable.
-
-``` irb
->> light = Stoplight::Light.new('example-6') { fail }.
-..   with_timeout(1)
-=> #<Stoplight::Light:...>
->> light.run
-RuntimeError:
->> light.run
-RuntimeError:
->> light.run
-Switching example-6 from green to red because RuntimeError
-RuntimeError:
->> sleep(1)
-=> 1
->> light.color
-=> "yellow"
->> light.run
-RuntimeError:
+Stoplights will automatically attempt to recover after a certain
+amount of time.  A light in the red state for longer than the timeout
+will transition to the yellow state. This timeout is customizable.
+
+``` rb
+light = Stoplight('example-6') { fail }
+  .with_timeout(1)
+# => #<Stoplight::Light:...>
+light.run
+# RuntimeError:
+light.run
+# RuntimeError:
+light.run
+# Switching example-6 from green to red because RuntimeError
+# RuntimeError:
+sleep(1)
+# => 1
+light.color
+# => "yellow"
+light.run
+# RuntimeError:
 ```
 
 Set the timeout to `-1` to disable automatic recovery.
 
 ### Rails
 
-Stoplight was designed to wrap Rails actions with minimal effort. Here's an
-example configuration:
+Stoplight was designed to wrap Rails actions with minimal effort.
+Here's an example configuration:
 
 ``` rb
 class ApplicationController < ActionController::Base
   around_action :stoplight
   private
   def stoplight(&block)
-    Stoplight::Light.new("#{params[:controller]}##{params[:action]}", &block)
+    Stoplight("#{params[:controller]}##{params[:action]}", &block)
       .with_allowed_errors([ActiveRecord::RecordNotFound])
       .with_fallback do |error|
         Rails.logger.error(error)
@@ -270,55 +296,39 @@ end
 
 ### Locking
 
-Although stoplights can operate on their own, occasionally you may want to
-override the default behavior. You can lock a light in either the green or red
-state using `set_state`.
-
-``` irb
->> light = Stoplight::Light.new('example-7') { true }
-=> #<Stoplight::Light:..>
->> light.run
-=> true
->> light.data_store.set_state(light, Stoplight::State::LOCKED_RED)
-=> "locked_red"
->> light.run
-Stoplight::Error::RedLight: example-7
+Although stoplights can operate on their own, occasionally you may
+want to override the default behavior. You can lock a light in
+either the green or red state using `set_state`.
+
+``` rb
+light = Stoplight('example-7') { true }
+# => #<Stoplight::Light:..>
+light.run
+# => true
+light.data_store.set_state(light, Stoplight::State::LOCKED_RED)
+# => "locked_red"
+light.run
+# Stoplight::Error::RedLight: example-7
 ```
 
-**Code in locked red lights may still run under certain conditions!** If you
-have configured a custom data store and that data store fails, Stoplight will
-switch over to using a blank in-memory data store. That means you will lose the
-locked state of any stoplights.
+**Code in locked red lights may still run under certain conditions!**
+If you have configured a custom data store and that data store
+fails, Stoplight will switch over to using a blank in-memory data
+store. That means you will lose the locked state of any stoplights.
 
 ## Credits
 
-Stoplight is brought to you by [@camdez][15] and [@tfausak][16] from
-[@OrgSync][17]. We were inspired by Martin Fowler's [CircuitBreaker][18]
+Stoplight is brought to you by [@camdez][] and [@tfausak][] from
+[@OrgSync][]. We were inspired by Martin Fowler's [CircuitBreaker][]
 article.
 
-If this gem isn't cutting it for you, there are a few alternatives, including:
-[circuit_b][19], [circuit_breaker][20], [simple_circuit_breaker][21], and
-[ya_circuit_breaker][22].
-
-[1]: https://github.com/orgsync/stoplight
-[2]: https://badge.fury.io/rb/stoplight.svg
-[3]: https://rubygems.org/gems/stoplight
-[4]: https://travis-ci.org/orgsync/stoplight.svg
-[5]: https://travis-ci.org/orgsync/stoplight
-[6]: https://img.shields.io/coveralls/orgsync/stoplight.svg
-[7]: https://coveralls.io/r/orgsync/stoplight
-[8]: https://codeclimate.com/github/orgsync/stoplight/badges/gpa.svg
-[9]: https://codeclimate.com/github/orgsync/stoplight
-[10]: https://gemnasium.com/orgsync/stoplight.svg
-[11]: https://gemnasium.com/orgsync/stoplight
-[12]: https://github.com/orgsync/stoplight-admin
-[13]: https://rubygems.org/gems/redis
-[14]: https://rubygems.org/gems/hipchat
-[15]: https://github.com/camdez
-[16]: https://github.com/tfausak
-[17]: https://github.com/OrgSync
-[18]: http://martinfowler.com/bliki/CircuitBreaker.html
-[19]: https://github.com/alg/circuit_b
-[20]: https://github.com/wsargent/circuit_breaker
-[21]: https://github.com/soundcloud/simple_circuit_breaker
-[22]: https://github.com/wooga/circuit_breaker
+Emoji provided free by [Emoji One][].
+
+[stoplight-admin]: https://github.com/orgsync/stoplight-admin
+[the redis gem]: https://rubygems.org/gems/redis
+[the hipchat gem]: https://rubygems.org/gems/hipchat
+[@camdez]: https://github.com/camdez
+[@tfausak]: https://github.com/tfausak
+[@orgsync]: https://github.com/OrgSync
+[circuitbreaker]: http://martinfowler.com/bliki/CircuitBreaker.html
+[emoji one]: http://www.emojione.com

data/lib/stoplight.rb

@@ -1,5 +1,10 @@
 # coding: utf-8
 
+module Stoplight
+end
+
+require 'stoplight/version'
+
 require 'stoplight/color'
 require 'stoplight/error'
 require 'stoplight/failure'
@@ -20,5 +25,7 @@ require 'stoplight/default'
 require 'stoplight/light/runnable'
 require 'stoplight/light'
 
-module Stoplight
+# @see Stoplight::Light#initialize
+def Stoplight(name, &code) # rubocop:disable Style/MethodName
+  Stoplight::Light.new(name, &code)
 end

data/lib/stoplight/data_store/base.rb

@@ -2,35 +2,53 @@
 
 module Stoplight
   module DataStore
+    # @abstract
     class Base
+      # @return [Array<String>]
       def names
         fail NotImplementedError
       end
 
+      # @param _light [Light]
+      # @return [Array(Array<Failure>, String)]
       def get_all(_light)
         fail NotImplementedError
       end
 
+      # @param _light [Light]
+      # @return [Array<Failure>]
       def get_failures(_light)
         fail NotImplementedError
       end
 
+      # @param _light [Light]
+      # @param _failure [Failure]
+      # @return [Fixnum]
       def record_failure(_light, _failure)
         fail NotImplementedError
       end
 
+      # @param _light [Light]
+      # @return [Array<Failure>]
       def clear_failures(_light)
         fail NotImplementedError
       end
 
+      # @param _light [Light]
+      # @return [String]
       def get_state(_light)
         fail NotImplementedError
       end
 
+      # @param _light [Light]
+      # @param _state [String]
+      # @return [String]
       def set_state(_light, _state)
         fail NotImplementedError
       end
 
+      # @param _light [Light]
+      # @return [String]
       def clear_state(_light)
         fail NotImplementedError
       end

data/lib/stoplight/data_store/memory.rb

@@ -2,6 +2,7 @@
 
 module Stoplight
   module DataStore
+    # @see Base
     class Memory < Base
       def initialize
         @data = {}

data/lib/stoplight/data_store/redis.rb

@@ -2,10 +2,12 @@
 
 module Stoplight
   module DataStore
+    # @see Base
     class Redis < Base
       KEY_PREFIX = 'stoplight'.freeze
       KEY_SEPARATOR = ':'.freeze
 
+      # @param redis [::Redis]
       def initialize(redis)
         @redis = redis
       end

data/lib/stoplight/failure.rb

@@ -5,14 +5,23 @@ require 'time'
 
 module Stoplight
   class Failure
+    # @return [String]
     attr_reader :error_class
+    # @return [String]
     attr_reader :error_message
+    # @return [Time]
     attr_reader :time
 
+    # @param error [Exception]
+    # @return (see #initialize)
     def self.from_error(error)
       new(error.class.name, error.message, Time.new)
     end
 
+    # @param json [String]
+    # @return (see #initialize)
+    # @raise [JSON::ParserError]
+    # @raise [ArgumentError]
     def self.from_json(json)
       object = JSON.parse(json)
 
@@ -23,18 +32,24 @@ module Stoplight
       new(error_class, error_message, time)
     end
 
+    # @param error_class [String]
+    # @param error_message [String]
+    # @param time [Time]
     def initialize(error_class, error_message, time)
       @error_class = error_class
       @error_message = error_message
       @time = time
     end
 
+    # @param other [Failure]
+    # @return [Boolean]
     def ==(other)
       error_class == other.error_class &&
         error_message == other.error_message &&
         time == other.time
     end
 
+    # @return [String]
     def to_json
       JSON.generate(
         error: {

data/lib/stoplight/light.rb

@@ -4,19 +4,31 @@ module Stoplight
   class Light
     include Runnable
 
+    # @return [Array<Exception>]
     attr_reader :allowed_errors
+    # @return [Proc]
     attr_reader :code
+    # @return [DataStore::Base]
     attr_reader :data_store
+    # @return [Proc]
     attr_reader :error_notifier
+    # @return [Proc, nil]
     attr_reader :fallback
+    # @return [String]
     attr_reader :name
+    # @return [Array<Notifier::Base>]
     attr_reader :notifiers
+    # @return [Fixnum]
     attr_reader :threshold
+    # @return [Float]
     attr_reader :timeout
 
     class << self
+      # @return [DataStore::Base]
       attr_accessor :default_data_store
+      # @return [Proc]
       attr_accessor :default_error_notifier
+      # @return [Array<Notifier::Base>]
       attr_accessor :default_notifiers
     end
 
@@ -24,6 +36,8 @@ module Stoplight
     @default_error_notifier = Default::ERROR_NOTIFIER
     @default_notifiers = Default::NOTIFIERS
 
+    # @param name [String]
+    # @yield []
     def initialize(name, &code)
       @name = name
       @code = code
@@ -37,36 +51,50 @@ module Stoplight
       @timeout = Default::TIMEOUT
     end
 
+    # @param allowed_errors [Array<Exception>]
+    # @return [self]
     def with_allowed_errors(allowed_errors)
       @allowed_errors = Default::ALLOWED_ERRORS + allowed_errors
       self
     end
 
+    # @param data_store [DataStore::Base]
+    # @return [self]
     def with_data_store(data_store)
       @data_store = data_store
       self
     end
 
+    # @yieldparam error [Exception]
+    # @return [self]
     def with_error_notifier(&error_notifier)
       @error_notifier = error_notifier
       self
     end
 
+    # @yieldparam error [Exception, nil]
+    # @return [self]
     def with_fallback(&fallback)
       @fallback = fallback
       self
     end
 
+    # @param notifiers [Array<Notifier::Base>]
+    # @return [self]
     def with_notifiers(notifiers)
       @notifiers = notifiers
       self
     end
 
+    # @param threshold [Fixnum]
+    # @return [self]
     def with_threshold(threshold)
       @threshold = threshold
       self
     end
 
+    # @param timeout [Float]
+    # @return [self]
     def with_timeout(timeout)
       @timeout = timeout
       self

data/lib/stoplight/light/runnable.rb

@@ -3,6 +3,7 @@
 module Stoplight
   class Light
     module Runnable
+      # @return [String]
       def color
         failures, state = failures_and_state
         failure = failures.first
@@ -16,6 +17,7 @@ module Stoplight
         end
       end
 
+      # @raise [Error::RedLight]
       def run
         case color
         when Color::GREEN then run_green

data/lib/stoplight/notifier/base.rb

@@ -2,7 +2,13 @@
 
 module Stoplight
   module Notifier
+    # @abstract
     class Base
+      # @param _light [Light]
+      # @param _from_color [String]
+      # @param _to_color [String]
+      # @param _error [Exception, nil]
+      # @return [String]
       def notify(_light, _from_color, _to_color, _error)
         fail NotImplementedError
       end

data/lib/stoplight/notifier/hip_chat.rb

@@ -2,6 +2,7 @@
 
 module Stoplight
   module Notifier
+    # @see Base
     class HipChat < Base
       DEFAULT_OPTIONS = {
         color: 'purple',
@@ -9,11 +10,22 @@ module Stoplight
         notify: true
       }.freeze
 
+      # @return [Proc]
       attr_reader :formatter
+      # @return [::HipChat::Client]
       attr_reader :hip_chat
+      # @return [Hash{Symbol => Object}]
       attr_reader :options
+      # @return [String]
       attr_reader :room
 
+      # @param hip_chat [::HipChat::Client]
+      # @param room [String]
+      # @param formatter [Proc, nil]
+      # @param options [Hash{Symbol => Object}]
+      # @option options [String] :color
+      # @option options [String] :message_format
+      # @option options [Boolean] :notify
       def initialize(hip_chat, room, formatter = nil, options = {})
         @hip_chat = hip_chat
         @room = room

data/lib/stoplight/notifier/io.rb

@@ -4,10 +4,15 @@ require 'stringio'
 
 module Stoplight
   module Notifier
+    # @see Base
     class IO < Base
+      # @return [Proc]
       attr_reader :formatter
+      # @return [::IO]
       attr_reader :io
 
+      # @param io [::IO]
+      # @param formatter [Proc, nil]
       def initialize(io, formatter = nil)
         @io = io
         @formatter = formatter || Default::FORMATTER

data/lib/stoplight/version.rb

@@ -0,0 +1,5 @@
+# coding: utf-8
+
+module Stoplight
+  VERSION = Gem::Version.new('0.5.2')
+end

data/spec/stoplight/version_spec.rb

@@ -0,0 +1,9 @@
+# coding: utf-8
+
+require 'spec_helper'
+
+describe Stoplight::VERSION do
+  it 'is a gem version' do
+    expect(described_class).to be_a(Gem::Version)
+  end
+end

data/spec/stoplight_spec.rb

@@ -7,3 +7,15 @@ describe Stoplight do
     expect(described_class).to be_a(Module)
   end
 end
+
+describe 'Stoplight' do
+  subject(:light) { Stoplight(name, &code) }
+  let(:name) { ('a'..'z').to_a.shuffle.join }
+  let(:code) { -> {} }
+
+  it 'creates a stoplight' do
+    expect(light).to be_a(Stoplight::Light)
+    expect(light.name).to eql(name)
+    expect(light.code).to eql(code)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stoplight
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
 platform: ruby
 authors:
 - Cameron Desautels
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-19 00:00:00.000000000 Z
+date: 2015-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
@@ -74,56 +74,56 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '10.3'
+        version: '10.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '10.3'
+        version: '10.4'
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '3.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '3.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '0.27'
+        version: '0.29'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '0.27'
+        version: '0.29'
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement
@@ -181,6 +181,7 @@ files:
 - lib/stoplight/notifier/hip_chat.rb
 - lib/stoplight/notifier/io.rb
 - lib/stoplight/state.rb
+- lib/stoplight/version.rb
 - spec/spec_helper.rb
 - spec/stoplight/color_spec.rb
 - spec/stoplight/data_store/base_spec.rb
@@ -197,6 +198,7 @@ files:
 - spec/stoplight/notifier/io_spec.rb
 - spec/stoplight/notifier_spec.rb
 - spec/stoplight/state_spec.rb
+- spec/stoplight/version_spec.rb
 - spec/stoplight_spec.rb
 homepage: https://github.com/orgsync/stoplight
 licenses:
@@ -218,7 +220,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.4
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Traffic control for code.
@@ -239,5 +241,6 @@ test_files:
 - spec/stoplight/notifier/io_spec.rb
 - spec/stoplight/notifier_spec.rb
 - spec/stoplight/state_spec.rb
+- spec/stoplight/version_spec.rb
 - spec/stoplight_spec.rb
 has_rdoc: