factis 0.0.7 → 0.0.8

data/README.md

@@ -104,6 +104,11 @@ recall_fact(:some_foo)
   => #<Foo:0x007ffd84394728>
 ```
 
+## Formal Documentation ##
+
+The actual library docs can be read
+[over on rubydoc](http://rubydoc.info/gems/factis/frames).
+
 ## Contributing ##
 
 Do you use git-flow? I sure do. Please base anything you do off of

data/lib/factis.rb

@@ -1,27 +1,66 @@
 require 'factis/memory'
 
+# This module contains syntactic sugar for the methods in Factis::Memory.
+# The purpose is, basically, to make the methods easily injected into,
+# say, Cucumber via extend.
+
 module Factis
 
+  # Forget all of the known facts
+  # @see Factis::Memory.reset!
+
   def clear_all_facts!
     Factis::Memory.reset!
   end
 
+  # Returns the entire facts hash
+  # @return [Hash] the facts hash
+  # @see Factis::Memory.all_facts
+
   def all_facts
     Factis::Memory.all_facts
   end
 
+  # Memorize the given content, keyed by the given fact key. This wrapper
+  # does not allow for overwriting of a fact, and an atttempt to do so will
+  # raise an error.
+  # @param fact a key suitable for use in a Hash
+  # @param content (Object) the content to store
+  # @return [Object] the content that was stored
+  # @raise [RuntimeError] if the fact key is already in the facts hash
+  # @see Factis::Memory.memorize
+
   def memorize_fact(fact, content)
     Factis::Memory.memorize(fact, content)
   end
 
+  # This method is equivalent to memorize_fact in all ways, save that it
+  # disregards the possible existence of the fact key within the internal
+  # hash.
+  # @note This undermines the goal of *safely* tracking state. Please refrain
+  #   from using it if at all possible.
+  # @see Factis#memorize_fact
+  # @see Factis::Memory.memorize
+
   def indifferently_memorize_fact(fact, content)
     Factis::Memory.memorize(fact, content, :overwrite => true)
   end
 
+  # Get fact content by key, raising an error for an unknown fact
+  # @param fact the key of the fact to retrieve
+  # @return [Object] the content of the recalled fact
+  # @raise [RuntimeError] if the key is not in the fact hash
+
   def recall_fact(fact)
     Factis::Memory.recall(fact)
   end
 
+  # Removes the given fact (key) from internal storage, raising an error for
+  # an unknown fact
+  # @param fact the key of the fact to remove
+  # @return [Object] the content of the removed fact
+  # @raise [RuntimeError] if the key is not in the fact hash
+
   def forget_fact(fact)
     Factis::Memory.forget(fact)
   end

data/lib/factis/memory.rb

@@ -1,16 +1,35 @@
 module Factis
   class Memory
 
-    def self.init_memory!
-      @facts = Hash.new
+    class << self
+      private
+      def init_memory!
+        @facts = Hash.new
+      end
     end
 
+    # Get the entire facts hash
+    #
+    # @return [Hash] all facts that have been stored
+
     def self.all_facts
       init_memory! if @facts.nil?
       @facts
     end
 
-    def self.memorize(fact, content, options = {})
+    # Stores content as fact, optionally overwriting said content
+    #
+    # @param fact the key for the fact hash
+    # @param content [Object] the content for the fact
+    # @param options [Hash] The only key checked is :overwrite
+    #   a boolean defaulting to false.
+    #
+    # @return [Object] the fact content
+    #
+    # @raise [RuntimeError] if the fact key is already known and :overwrite
+    #   is not active.
+
+    def self.memorize(fact, content, options = {:overwrite => false})
       init_memory! if @facts.nil?
       if known_fact?(fact)
         unless options[:overwrite] == true
@@ -20,11 +39,25 @@ module Factis
       @facts[fact] = content
     end
 
+    # Determines if the given fact key is already known
+    #
+    # @param fact the fact key to check
+    #
+    # @return [Boolean] true if the key is known, false otherwise
+
     def self.known_fact?(fact)
       init_memory! if @facts.nil?
       @facts.keys.include?(fact)
     end
 
+    # Removes the given fact (key) from internal storage
+    #
+    # @param fact the key of the fact to remove
+    #
+    # @return [Object] the content of the removed fact
+    #
+    # @raise [RuntimeError] if the key is not in the fact hash
+
     def self.forget(fact)
       init_memory! if @facts.nil?
       unless known_fact?(fact)
@@ -33,6 +66,14 @@ module Factis
       @facts.delete(fact)
     end
 
+    # Get fact content by key
+    #
+    # @param fact the key of the fact to retrieve
+    #
+    # @return [Object] the content of the recalled fact
+    #
+    # @raise [RuntimeError] if the key is not in the fact hash
+
     def self.recall(fact)
       init_memory! if @facts.nil?
       unless known_fact?(fact)
@@ -41,6 +82,8 @@ module Factis
       @facts[fact]
     end
 
+    # Clear the entire facts hash
+
     def self.reset!
       init_memory! if @facts.nil?
       @facts.clear

data/lib/factis/version.rb

@@ -1,3 +1,3 @@
 module Factis
-  VERSION = '0.0.7'
+  VERSION = '0.0.8'
 end

data/spec/factis/memory_spec.rb

@@ -93,7 +93,7 @@ describe Factis::Memory do
   describe %{.init_memory!} do
     it %{should instantiate a new Hash for the memory} do
       old = memory.all_facts.__id__
-      memory.init_memory!
+      memory.class_eval('init_memory!')
       memory.all_facts.__id__.should_not == old
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: factis
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-07 00:00:00.000000000 Z
+date: 2013-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -82,3 +82,4 @@ test_files:
 - spec/factis/memory_spec.rb
 - spec/factis_spec.rb
 - spec/spec_helper.rb
+has_rdoc: