lib/cogy/command.rb in cogy-0.3.0 vs lib/cogy/command.rb in cogy-0.4.0

@@ -1,28 +1,60 @@
 module Cogy
-  # {Command} represents a user-defined registered command that can be used
-  # in the chat. It contains the Cog-related stuff (ie. everything that
-  # needs to be in the bundle config) and a block that will run and return
-  # the result (ie. handler).
+  # {Command} represents a user-defined, registered command that can be used
+  # in the chat. It contains information about Cog-related stuff (ie. everything that
+  # needs to be in the bundle config like args & opts) and the block that will
+  # return the result ({Command#handler}).
   class Command
-    # The name of the command. Also used in {Cogy.bundle_config}.
-    #
     # @return [String]
     attr_reader :name
 
-    # The code that will run when the command is invoked
-    #
     # @return [Proc]
     attr_reader :handler
 
-    # Attributes related to the bundle config in Cog
-    attr_reader :args, :opts, :desc, :long_desc, :examples, :rules
+    # @return [Array]
+    attr_reader :args
 
-    # The Cog template that the command should use
+    # @return [Hash{Symbol=>Hash}]
+    attr_reader :opts
+
+    # @return [String]
+    attr_reader :desc
+
+    # @return [String]
+    attr_reader :long_desc
+
+    # @return [String]
+    attr_reader :examples
+
+    # @return [Array]
+    attr_reader :rules
+
+    # @return [String]
     attr_reader :template
 
-    # See {Cogy.on}
-    def initialize(name, handler, args: [], opts: {}, desc:, long_desc: nil, examples: nil, rules: nil, template: nil)
+    # This is typically used via {Cogy.on} which also registers the newly
+    # created {Command}.
+    #
+    # @param name      [String, Symbol] the name of the command. This is how the
+    #   command will be invoked in the chat.
+    #
+    # @param handler   [Proc] the code that will run when the command is invoked
+    #
+    # @param args      [Array<Symbol, String>, Symbol, String] the arguments
+    #   accepted by the command
+    #
+    # @param opts      [Hash{Symbol=>Hash}] the options accepted by the command
+    # @param desc      [String] the description
+    # @param long_desc [String] the long description
+    # @param examples  [String] usage examples of the command
+    # @param rules     [Array] the command rules
+    # @param template  [String] the name of the template to use
+    #
+    # @raise [ArgumentError] if {#opts} are invalid
+    #
+    # @see Cogy.on
+    def initialize(name, handler, args: [], opts: {}, desc:, long_desc: nil,
+                   examples: nil, rules: nil, template: nil)
       @name = name.to_s
       @handler = handler
       @args = [args].flatten.map!(&:to_s)
       @opts = opts.with_indifferent_access
       @desc = desc