inheritable_setting.rb in grape-0.13.0

- old
+ new

@@ -1,36 +1,50 @@
 module Grape
   module Util
+    # A branchable, inheritable settings object which can store both stackable
+    # and inheritable values (see InheritableValues and StackableValues).
     class InheritableSetting
       attr_accessor :route, :api_class, :namespace, :namespace_inheritable, :namespace_stackable
       attr_accessor :parent, :point_in_time_copies
 
+      # Retrieve global settings.
       def self.global
         @global ||= {}
       end
 
-      def self.reset_global! # only for testing
+      # Clear all global settings.
+      # @api private
+      # @note only for testing
+      def self.reset_global!
         @global = {}
       end
 
+      # Instantiate a new settings instance, with blank values. The fresh
+      # instance can then be set to inherit from an existing instance (see
+      # #inherit_from).
       def initialize
         self.route = {}
         self.api_class = {}
         self.namespace = InheritableValues.new # only inheritable from a parent when
-        # used with a mount, or should every API::Class be a seperate namespace by default?
+        # used with a mount, or should every API::Class be a separate namespace by default?
         self.namespace_inheritable = InheritableValues.new
         self.namespace_stackable = StackableValues.new
 
         self.point_in_time_copies = []
 
         self.parent = nil
       end
 
+      # Return the class-level global properties.
       def global
         self.class.global
       end
 
+      # Set our inherited values to the given parent's current values. Also,
+      # update the inherited values on any settings instances which were forked
+      # from us.
+      # @param parent [InheritableSetting]
       def inherit_from(parent)
         return if parent.nil?
 
         self.parent = parent
 
@@ -39,10 +53,14 @@
         self.route = parent.route.merge(route)
 
         point_in_time_copies.map { |cloned_one| cloned_one.inherit_from parent }
       end
 
+      # Create a point-in-time copy of this settings instance, with clones of
+      # all our values. Note that, should this instance's parent be set or
+      # changed via #inherit_from, it will copy that inheritence to any copies
+      # which were made.
       def point_in_time_copy
         self.class.new.tap do |new_setting|
           point_in_time_copies << new_setting
           new_setting.point_in_time_copies = []
 
@@ -54,13 +72,16 @@
 
           new_setting.inherit_from(parent)
         end
       end
 
+      # Resets the instance store of per-route settings.
+      # @api private
       def route_end
         @route = {}
       end
 
+      # Return a serializable hash of our values.
       def to_hash
         {
           global: global.clone,
           route: route.clone,
           namespace: namespace.to_hash,