cogy.rb in cogy-0.4.0

- old
+ new

@@ -2,25 +2,22 @@
 require "cogy/command"
 require "cogy/context"
 
 module Cogy
   # The supported Cog bundle config version.
-  #
-  # @see http://docs.operable.io/docs/bundle-configs
   COG_BUNDLE_VERSION = 4
 
   # Holds all the registered {Command} objects. Not to be messed with.
   @@commands = {}
   mattr_accessor :commands
 
-  # Configuration related to the Cog bundle. Used in {Cogy.bundle_config}
-  # in order to generate the bundle config YAML.
+  # Configuration related to the Cog bundle. Used in {Cogy.bundle_config}.
   #
   # @see https://cog-book.operable.io/#_the_config_file
   @@bundle = {
     # The bundle name
-    name: "cogy",
+    name: "myapp",
 
     # The bundle description
     description: "Cog commands generated from Cogy",
 
     # The bundle version.
@@ -38,43 +35,35 @@
     cogy_executable: "/usr/bin/cogy"
   }
   mattr_accessor :bundle
 
   # The Cog templates. Used in {Cogy.bundle_config}.
-  #
-  # @see https://cog-book.operable.io/#_templates
   @@templates = {}
   mattr_accessor :templates
 
   # Paths where the files that define the commands will be searched in the
   # host application.
   @@command_load_paths = ["cogy"]
   mattr_accessor :command_load_paths
 
-  # Registers a command to Cogy. All the options passed are used solely for
-  # generating the bundle config (ie. {Cogy.bundle_config}). The passed block
-  # is the code that will get executed when the command is invoked.
+  # Initializes a new {Command} and registers it. All the options passed are
+  # used when generating the bundle config in {Cogy.bundle_config}.
   #
-  # The last value of the block is what will get printed as the result of the
-  # command. It should be a string. If you want to return early in a point
-  # inside the block, use `next` instead of `return`.
+  # The given block is the code that will execute when the command is invoked.
+  # The return value of that block is what will get returned as a result
+  # back to Cog.
   #
-  # Inside the command block, there are the public attributes of {Context}
-  # available.
+  # Inside the command block the public attributes of {Context} are
+  # available in addition to any user-defined handlers.
   #
   # @param cmd_name [String, Symbol] the name of the command. This is how the
   #   command will be invoked in the chat.
-  # @param [Hash] opts the options to create the command with. All these options
+  # @param opts [Hash] the options to create the command with. All these options
   #   are used solely for generating the bundle config for Cog, thus they map
   #   directly to Cog's bundle config format.
   #   See https://cog-book.operable.io/#_the_config_file for more information.
-  # @option opts [Array<Symbol, String>, Symbol, String] :args ([])
-  # @option opts [Hash{Symbol=>Hash}] :opts ({})
-  # @option opts [String] :desc required
-  # @option opts [String] :long_desc (nil)
-  # @option opts [String] :examples (nil)
-  # @option opts [Array] :rules (["allow"])
+  #   For documentation on what's supported right now see {Command#initialize}.
   #
   # @example
   #   Cogy.on "calc",
   #     args: [:a, :b],
   #     opts: { op: { description: "The operation to perform", type: "string", required: true } },
@@ -88,23 +77,22 @@
   #     rules: ["allow"] do
   #     result = args.map(&:to_i).inject(&opts["op"].to_sym)
   #     "Hello #{user}, the answer is: #{result}"
   #   end
   #
-  # @return [void]
+  # @return [Command] the created command
   #
-  # @note If you want to return early in a point inside a command block,
-  #   `next` should be used instead of `return`, due to the way Proc objects
-  #   work in Ruby.
+  # @note to return early inside a command block, `next` should be used instead
+  #   of `return` due to the way Proc objects work in Ruby.
   def self.on(cmd_name, opts = {}, &handler)
     cmd = Command.new(cmd_name, handler, opts)
     cmd.register!
   end
 
   # Generates the bundle config
   #
-  # @return [Hash]
+  # @return [Hash] the bundle config
   def self.bundle_config
     version = if bundle[:version].respond_to?(:call)
                 bundle[:version].call
               else
                 bundle[:version]
@@ -159,24 +147,24 @@
     yield self
   end
 
   # Defines a user helper method that can be used throughout commands.
   #
-  # @param [Symbol] name the name of the helper
-  # @param [Proc] blk the helper body
+  # @param name [Symbol] the name of the helper
+  # @param blk [Proc] the helper body
   #
   # @return [void]
   #
-  # @note User helpers also have access to the default helpers like `user`, `env`
-  #   etc.
-  #
   # @example
   #   Cogy.configure do |c|
   #     helper(:user) { User.find_by(slack_handle: handle) }
   #
   #     # a helper that accepts an argument
   #     helper(:format) { |answer| answer.titleize }
   #   end
+  #
+  # @note User helpers also have access to the default helpers like `user`, `env`
+  #   etc.
   def self.helper(name, &blk)
     Context.class_eval { define_method(name, blk) }
   end
 end