Small documentation improvements

lib/object_identifier.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-# ObjectIdentifier is the base namespace for all modules/classes related to the
-# object_identifier gem.
+# ObjectIdentifier is the top-level namespace/module for this gem.
 module ObjectIdentifier
+  # :reek:LongParameterList
+
   # ObjectIdentifier.call is the main entry point for use of this gem. In
   # typical usage, however, this method will almost exclusively just be called
   # by {Object#identify}, as defined in lib/core_ext/object.rb.
-  # :reek:LongParameterList
   def self.call(
         objects,
         *attributes,
@@ -80,8 +80,14 @@ def default_attributes=(value)
 require "object_identifier/version"
 require "object_identifier/array_wrap"
 require "object_identifier/parameters"
+
+# FORMATTERS
+
 require "object_identifier/formatters/base_formatter"
 require "object_identifier/formatters/string_formatter"
+
+# CORE EXTENSIONS
+
 require "core_ext/object"
 require "core_ext/string"
 require "core_ext/symbol"

lib/object_identifier/array_wrap.rb

@@ -7,6 +7,10 @@
 class ObjectIdentifier::ArrayWrap
   # :reek:NilCheck
   # :reek:ManualDispatch
+
+  # Dispatch "Array Wrapping" logic on the given `object`.
+  #
+  # @param object The object(s) to attempt to Array wrap.
   def self.call(object)
     if object.nil?
       []

lib/object_identifier/formatters/base_formatter.rb

@@ -10,8 +10,8 @@ def self.call(...)
     new(...).call
   end
 
-  # @param objects [Object, [Object, ...]] the object(s) to be interrogated for
-  #   String values to be added to the output String
+  # @param objects [Object, [Object, ...]] The object(s) to be interrogated for
+  #   String values to be added to the output String.
   # @param parameters [ObjectIdentifier::Parameters]
   def initialize(objects, parameters: ObjectIdentifier::Parameters.build)
     @objects = ObjectIdentifier::ArrayWrap.(objects)

lib/object_identifier/formatters/string_formatter.rb

@@ -3,14 +3,14 @@
 # ObjectIdentifier::StringFormatter builds a String to identify the
 # given object(s).
 class ObjectIdentifier::StringFormatter < ObjectIdentifier::BaseFormatter
-  # The String to output when the {#objects} is empty.
+  # The String to output when {#objects} is empty.
   NO_OBJECTS_INDICATOR = "[no objects]"
 
   # Output the self-identifying string for the given object(s). Will either
   # return a single object representation or a list of object
   # representations, based on the number of objects we're identifying.
   #
-  # @return [String] a string that identifies the object(s)
+  # @return [String] A string that identifies the object(s).
   def call
     if objects.none?
       NO_OBJECTS_INDICATOR
@@ -85,15 +85,15 @@ class Item
     attr_reader :object,
                 :parameters
 
-    # @param object [Object] the object to be interrogated for String values to
-    #   be added to the output String
+    # @param object [Object] The object to be interrogated for String values to
+    #   be added to the output String.
     # @param parameters [ObjectIdentifier::Parameters]
     def initialize(object, parameters)
       @object = object
       @parameters = parameters
     end
 
-    # @return [String] the self-identifying String for {object}.
+    # @return [String] The self-identifying String for {#object}.
     def call
       return NO_OBJECTS_INDICATOR if blank?
 
@@ -102,8 +102,9 @@ def call
 
     private
 
-    # Simple version of Rails' Object#blank? method.
     # :reek:NilCheck
+
+    # Simple version of Rails' Object#blank? method.
     def blank?
       object.nil? || object == [] || object == {}
     end
@@ -117,6 +118,7 @@ def formatted_attributes
     end
 
     # :reek:DuplicateMethodCall
+
     def attributes_formatter
       @attributes_formatter ||=
         if attributes_hash.one?
@@ -126,8 +128,9 @@ def attributes_formatter
         end
     end
 
-    # @return [Hash]
     # :reek:ManualDispatch
+
+    # @return [Hash]
     def attributes_hash
       @attributes_hash ||=
         attributes.each_with_object({}) { |key, acc|

lib/object_identifier/parameters.rb

@@ -22,12 +22,12 @@ def self.build(attributes: [], formatter_options: {})
       formatter_options: formatter_options.to_h)
   end
 
-  # @param attributes [Array, *args] a list of method calls to interrogate the
-  #   given object(s) with
-  # @option formatter_options[:limit] [Integer, nil] (nil) a given limit on the
-  #   number of objects to interrogate
-  # @option formatter_options[:klass] [#to_s] a preferred type name for
-  #   identifying the given object(s) as
+  # @param attributes [Array, *args] A list of method calls to interrogate the
+  #   given object(s) with.
+  # @option formatter_options[:limit] [Integer, nil] A given limit on the number
+  #   of objects to interrogate.
+  # @option formatter_options[:klass] [#to_s] A preferred type name for
+  #   identifying the given object(s) as.
   def initialize(
         attributes: [],
         formatter_options: {})