state_gate 1.2.3 → 1.3.0

data/lib/state_gate.rb

@@ -14,9 +14,9 @@ I18n.load_path << File.expand_path('state_gate/locale/state_gate_en.yml', __dir_
 # Builds and attaches a _StateGate::Engine_  to the desired ActiveRecord String
 # attribute.
 #
-# *States* and *transitions* are provided within a configuration block, enabling
-# the _state_gate_ to ensure that only defined *states* are accepted as values
-# for the attribute, and that *states* may only transition to allowed *states*.
+# _States_ and _transitions_ are provided within a configuration block, enabling
+# the _state-gate_ to ensure that only defined _states_ are accepted as values
+# for the attribute, and that _states_ may only transition to other allowed _states_.
 #
 #   Class User
 #     include StateGate
@@ -27,12 +27,12 @@ I18n.load_path << File.expand_path('state_gate/locale/state_gate_en.yml', __dir_
 #   end
 #
 #
-# == Attribute Name
+# == The Attribute Name
 #
 # The +attribute_name+ *must* be:
-# * a Symbol
-# * the name of a database String column attribute
-# * not an aliased attribute name
+# - a Symbol
+# - the name of a database String column attribute
+# - not an aliased attribute name
 #
 #
 # == Configuration Options
@@ -42,75 +42,79 @@ I18n.load_path << File.expand_path('state_gate/locale/state_gate_en.yml', __dir_
 #
 # Options include:
 #
-# === | state
-# Required name for the new state, supplied as a Symbol. The +state-gate+ requires
-# a minimum of two states to be defined.
+# [state]
+#   Required name for the new state, supplied as a Symbol. The `state-gate` requires
+#   a minimum of two states to be defined.
 #     state :state_name
 #
 #
-# [:transitions_to]
-#   An optional list of the other state that this state is allowed to change to.
-#     state :state_1, transtions_to: [:state_2, :state_3, :state_4]
-#     state :state_2, transtions_to: :state_4
-#     state :state_3, transtions_to: :any
-#     state :state_4
+#   **_:transitions_to_**
+#     An optional list of the other state that this state is allowed to change to.
+#       state :state_1, transtions_to: [:state_2, :state_3, :state_4]
+#       state :state_2, transtions_to: :state_4
+#       state :state_3, transtions_to: :any
+#       state :state_4
 #
-# [:human]
-#   An optional String name to used when displaying gthe state in a view. If no
-#   name is specified, it will default to +:state.titleized+.
-#     state :state_1, transtions_to: [:state_2, :state_3], human: "My State"
+#   **_:human_**
+#     An optional String name to used when displaying gthe state in a view. If no
+#     name is specified, it will default to +:state.titleized+.
+#       state :state_1, transtions_to: [:state_2, :state_3], human: "My State"
 #
 #
-# === | default
-# Optional setting to specify the default state for a new object. The state name
-# is given as a Symbol.
-#     default :state_name
+# [default]
+#   Optional setting to specify the default state for a new object. The state name
+#   is given as a Symbol.
+#       default :state_name
 #
 #
-# === | prefix
-# Optional setting to add a given Symbol before each state name when using Class Scopes.
-# This helps to differential between multiple attributes that have similar state names.
-#     prefix :before  # => Class.before_active
+# [prefix]
+#   Optional setting to add a given Symbol before each state name when using Class Scopes.
+#   This helps to differential between multiple attributes that have similar state names.
+#       prefix :before  #=> Class.before_active
 #
 #
-# === | suffix
-# Optional setting to add a given Symbol after each state name when using Class Scopes.
-# This helps to differential between multiple attributes that have similar state names.
-#     suffix :after  # => Class.active_after
+# [suffix]
+#   Optional setting to add a given Symbol after each state name when using Class Scopes.
+#   This helps to differential between multiple attributes that have similar state names.
+#       suffix :after  #=> Class.active_after
 #
 #
-# === | make_sequential
-# Optional setting to automatically add transitions from each state to both the
-# preceeding and following states.
-#     make_sequential
+# [make_sequential]
+#   Optional setting to automatically add transitions from each state to both the
+#   preceeding and following states.
+#       make_sequential
 #
-# [:one_way]
-#   Option to restrict the generated transitions to one directtion only: from each
-#   state to the follow state.
-#     make_sequential :one_way
+#   **_:one_way_**
+#     Option to restrict the generated transitions to one directtion only: from each
+#     state to the follow state.
+#       make_sequential :one_way
 #
-# [:loop]
-#   Option to add transitions from the last state to the first and, unless +:one_way+
-#   is specified, also from the first state to the last.
-#     make_sequential :one_way, :loop
+#   **_:loop_**
+#     Option to add transitions from the last state to the first and, unless +:one_way+
+#     is specified, also from the first state to the last.
+#       make_sequential :one_way, :loop
 #
 #
-# === | no_scopes
-# Optional setting to disable the generation of Class Scope helpers methods.
-#     no_scopes
+# [no_scopes]
+#   Optional setting to disable the generation of Class Scope helpers methods.
+#       no_scopes
 #
 module StateGate
 
   ##
-  # Configuration Error for reporting issues with the configuration when
-  # building a new state machine
-  class ConfigurationError < StandardError # :nodoc:
+  # Configuration Error for reporting an invalid configuration when
+  # building a new _state-gate_
+  #
+  class ConfigurationError < StandardError
   end
 
+
+
   ##
-  # Conflict Error for reporting when a generated method name
-  # conflicts with an existing method name
-  class ConflictError < StandardError # :nodoc:
+  # Conflict Error for reporting a generated method name
+  # conflicting with an existing method name
+  #
+  class ConflictError < StandardError
   end
 
 
@@ -120,10 +124,18 @@ module StateGate
 
   ##
   # Returns the Symbol version of the provided value as long as it responds to
-  # +#to_s+ and has no included whitespace in the resulting String.
+  # _#to_s_ and has no included whitespace in the resulting String.
+  #
+  # @param [String, #to_s] val
+  #   the string to convert in to a Symbol
   #
-  # Returns +nil+ if the coversion fails.
+  # @return [Symbol]
+  #   the converted string
   #
+  # @return [nil]
+  #   if the string cannot be converted
+  #
+  # @example
   #   StateGate.symbolize('Test')    #=> :test
   #
   #   StateGate.symbolize(:Test)     #=> :test
@@ -155,32 +167,47 @@ module StateGate
 
 
 
+    ##
     # When StateGate is included within a Class, check ActiveRecord is
-    # an ancestor and add the 'state_gate' method to the includeing Class
+    # an ancestor and add the 'state_gate' method to the including Class
+    #
+    # @param [Class]
+    #   the Class that is including this module
     #
-    def included(base) #:nodoc:
+    def included(base)
       ar_included = base.ancestors.include?(::ActiveRecord::Base)
       fail I18n.t('state_gate.included_err', base: base.name) unless ar_included
 
-      generate_state_gate_method_for(base)
+      _generate_state_gate_method_for(base)
     end
     private_class_method :included
 
 
 
+    ##
     # Raise an exception when StateGate is 'extend' by another Class, to let
     # the user know that it should be 'included'.
     #
-    def extended(base) #:nodoc:
+    # @param [Class]
+    #   the Class that is extending this module
+    #
+    # @raise [RuntimeErrror]
+    #   this module should _never_ be added through extension
+    #
+    def extended(base)
       fail I18n.t('state_gate.extended_err', base: base.name)
     end
 
 
 
+    ##
     # Calls an instance of StateGate::Builder to generate the
-    # 'state_gate' for the Klass attribute.
+    # _state_gate_ for the Klass attribute.
+    #
+    # @param [Class]
+    #   the Class the _state-gate_ is being attached to
     #
-    def generate_state_gate_method_for(klass)
+    def _generate_state_gate_method_for(klass)
       klass.define_singleton_method(:state_gate) do |attr_name = nil, &block|
         # Note: the builder does all it's work on initialize, so nothing more
         # to do here.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: state_gate
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.3.0
 platform: ruby
 authors:
 - CodeMeister
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-26 00:00:00.000000000 Z
+date: 2024-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -76,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.5.17
 signing_key:
 specification_version: 4
 summary: State management for ActiveRecord.