cog 0.0.19 → 0.0.20

data/lib/cog.rb

@@ -4,11 +4,13 @@ require 'cog/tool'
 require 'cog/version'
 require 'fileutils'
 
-# The static methods on this top level module mirror the commands available to
-# the +cog+ command line utility.
+# +cog+ is a command line utility that makes it a bit easier to organize a project
+# which uses code generation. These are the API docs, but you might want to read
+# the {https://github.com/ktonon/cog#readme general introduction} first.
 module Cog
 
   # Prepare the project in the present working directory for use with +cog+
+  # @return [nil]
   def self.initialize_project
     Object.new.instance_eval do
       class << self ; include Generator ; end
@@ -16,6 +18,7 @@ module Cog
       config = Config.instance
       touch_path config.project_generators_path
       touch_path config.project_templates_path
+      nil
     end
   end
   

data/lib/cog/config.rb

@@ -3,50 +3,57 @@ require 'singleton'
 
 module Cog
   
-  # This is a low level interface. It is mainly used by the Generator methods
+  # This is a low level interface. It is mainly used by the {Generator} methods
   # to determine where to find things, and where to put them. When +cog+ is used
-  # in a project the values of the singleton Config::instance should be configured using
-  # a Cogfile.
+  # in a project the values of the singleton {Config.instance} should be configured using
+  # a {Cogfile}.
   class Config
         
-    # Path to the project's +Cogfile+.
+    # @return [String] path to the project's {Cogfile}
     attr_reader :cogfile_path
 
-    # Default language in which to generated application source code
+    # @return [String] default language in which to generated application source code
     attr_reader :language
     
-    # Directory in which to find project generators
+    # @return [String] directory in which to find project generators
     attr_reader :project_generators_path
 
-    # Directory in which the project's +Cogfile+ is found
+    # @return [String] directory in which the project's {Cogfile} is found
     attr_reader :project_root
     
-    # Directory to which project source code is generated
+    # @return [String] directory to which project source code is generated
     attr_reader :project_source_path
 
-    # Directory in which to find custom project templates
+    # @return [String] directory in which to find custom project templates
     attr_reader :project_templates_path
     
-    # Are we operating in the context of a project?
-    # That is, could a Cogfile be found?
+    # @return [Boolean] are we operating in the context of a project?
     def project?
       !@project_root.nil?
     end
 
-    # A value which is set by the active tool
+    # @param value [String] a value which is set by the active tool
     attr_writer :tool_templates_path
     
-    # A value which is set by the active tool
+    # @return [String] a value which is set by the active tool
     attr_accessor :tool_generator_template
     
-    # A list of directories in which to find ERB template files.
-    # Priority should be given first to last.
+    # A list of directories in which to find ERB template files
+    #
+    # Templates should be looked for in the following order as determined by the list returned from this method
+    #
+    # * {#project_templates_path}, present if we are in the context of a {#project?}
+    # * tool templates, present if we are in the context of a tool (i.e. a tool has set {#tool_templates_path=})
+    # * +cog+ built-in templates, always present
+    #
+    # @return [Array<String>] a list of directories order with ascending priority
     def template_paths
       [@project_templates_path, @tool_templates_path, File.join(Config.gem_dir, 'templates')].compact
     end
     
     # Location of the installed cog gem
-    def self.gem_dir # :nodoc:
+    # @return [String] path to the cog gem
+    def self.gem_dir
       spec = Gem.loaded_specs['cog']
       if spec.nil?
         # The current __FILE__ is:
@@ -57,18 +64,17 @@ module Cog
       end
     end
     
-    # The singleton instance.
+    # The singleton instance
     #
     # Initialized using the Cogfile for the current project, if any can be
-    # found. If not, then #project? will be +false+ and all the +project_...+
+    # found. If not, then {#project?} will be +false+ and all the +project_...+
     # attributes will be +nil+.
     #
     # The Cogfile will be looked for in the present working directory. If none
     # is found there the parent directory will be checked, and then the
     # grandparent, and so on.
     # 
-    # ==== Returns
-    # An instance of Config.
+    # @return [Config] the singleton Config instance
     def self.instance
       return @instance if @instance
       @instance = self.new

data/lib/cog/config/cogfile.rb

@@ -3,32 +3,35 @@ module Cog
     
     # In your project's +Cogfile+, +self+ has been set to an instance of this class.
     #
-    # ==== Example +Cogfile+
+    # Typing <tt>cog init</tt> will create a +Cogfile+ in the present working directory.
+    # +Cogfile+ files are used to configure an instance of {Config}.
+    #
+    # @example
     #   project_generators_path 'cog/generators'
     #   project_templates_path 'cog/templates'
     #   project_source_path 'src'
     #   language 'c++'
     #
-    # Typing `cog init` will create a +Cogfile+ in the present working directory.
-    #
-    # +Cogfile+ files are used to configure an instance of Config.
     class Cogfile
-    
-      def initialize(config) # :nodoc:
+      
+      # Initialize with an instance of {Config}
+      # @api developer
+      # @param config [Config] the object which will be configured by this Cogfile
+      def initialize(config)
         @config = config
       end
     
-      # Interpret the Cogfile and initialize @config
-      def interpret # :nodoc:
+      # Interpret the +Cogfile+ at {Config#cogfile_path}
+      # @api developer
+      def interpret
         eval File.read(@config.cogfile_path), binding
       rescue Exception => e
         raise CogfileError.new(e.to_s)
       end
     
       # Define the directory in which to find project generators
-      # ==== Arguments
-      # * +path+ - A file system path
-      # * +absolute+ - If false, the path is relative to the directory containing the +Cogfile+
+      # @param path [String] a file system path
+      # @param absolute [Boolean] if +false+, the path is relative to {Config#project_root}
       def project_generators_path(path, absolute=false)
         @config.instance_eval do
           @project_generators_path = absolute ? path : File.join(project_root, path)
@@ -36,9 +39,8 @@ module Cog
       end
 
       # Define the directory in which to find custom project templates
-      # ==== Arguments
-      # * +path+ - A file system path
-      # * +absolute+ - If false, the path is relative to the directory containing the +Cogfile+
+      # @param path [String] a file system path
+      # @param absolute [Boolean] if +false+, the path is relative to {Config#project_root}
       def project_templates_path(path, absolute=false)
         @config.instance_eval do
           @project_templates_path = absolute ? path : File.join(project_root, path)
@@ -46,9 +48,8 @@ module Cog
       end
 
       # Define the directory to which project source code is generated
-      # ==== Arguments
-      # * +path+ - A file system path
-      # * +absolute+ - If false, the path is relative to the directory containing the +Cogfile+
+      # @param path [String] a file system path
+      # @param absolute [Boolean] if +false+, the path is relative to {Config#project_root}
       def project_source_path(path, absolute=false)
         @config.instance_eval do
           @project_source_path = absolute ? path : File.join(project_root, path)
@@ -56,8 +57,7 @@ module Cog
       end
 
       # Define the default language in which to generated application source code
-      # ==== Arguments
-      # * +lang+ - A code for the language. Acceptable values are <tt>c++</tt>.
+      # @param lang [String] a code for the language. Acceptable values are <tt>c++</tt>
       def language(lang)
         @config.instance_eval do
           @language = lang
@@ -65,7 +65,8 @@ module Cog
       end
     end
 
-    # For wrapping errors which occur during the processing of a +Cogfile+.
+    # For wrapping errors which occur during the processing of a {Cogfile}
+    # @api client
     class CogfileError < StandardError
       def message
         "in Cogfile, " + super

data/lib/cog/generator.rb

@@ -1,5 +1,6 @@
 require 'cog/config'
 require 'cog/errors'
+require 'cog/helpers'
 require 'erb'
 require 'rainbow'
 
@@ -7,12 +8,14 @@ module Cog
   
   # This module defines an interface which can be used by generator objects.
   # Specifically, it makes it easy to find ERB templates and render them into
-  # generated source code files, using the #stamp method.
+  # generated source code files, using the {#stamp} method.
   #
-  # For more details on writing generators see https://github.com/ktonon/cog#generators
+  # @see https://github.com/ktonon/cog#generators Introduction to Generators
   module Generator
 
-    # A list of available project generators
+    # List the available project generators
+    # @param verbose [Boolean] should full generator paths be listed?
+    # @return [Array<String>] a list of generator names
     def self.list(verbose=false)
       if Config.instance.project?
         x = Dir.glob(File.join Config.instance.project_generators_path, '*.rb')
@@ -23,15 +26,9 @@ module Cog
     end
     
     # Create a new generator
-    #
-    # ==== Arguments
-    # * +name+ - the name to use for the new generator
-    #
-    # ==== Options
-    # * +tool+ - the name of the tool to use (default: basic)
-    #
-    # ==== Returns
-    # Whether or not the generator was created successfully
+    # @param name [String] the name to use for the new generator
+    # @option opt [String] :tool ('basic') the name of the tool to use
+    # @return [Boolean] was the generator successfully created?
     def self.create(name, opt={})
       return false unless Config.instance.project?
 
@@ -72,12 +69,9 @@ module Cog
     end
     
     # Run the generator with the given name
-    #
-    # ==== Arguments
-    # * +name+ - the name of the generator
-    #
-    # ==== Returns
-    # Whether or not the generator could be found
+    # @param name [String] name of the generator as returned by {Generator.list}
+    # @option opt [Boolean] :verbose (false) in the case of an exception, should a full stack trace be written?
+    # @return [Boolean] was the generator run successfully?
     def self.run(name, opt={})
       filename = File.join Cog::Config.instance.project_generators_path, "#{name}.rb"
       if File.exists? filename
@@ -92,17 +86,10 @@ module Cog
       false
     end
 
-    # Get the template with the given name.
-    #
-    # ==== Parameters
-    # * +path+ - a path to a template file which is relative to
-    #   one of the template directories
-    #
-    # ==== Options
-    # * <tt>:absolute</tt> - is the +path+ argument absolute? (default: +false+)
-    #
-    # ==== Returns
-    # An instance of ERB.
+    # Get the template with the given name
+    # @param path [String] path to template file relative one of the {Config#template_paths}
+    # @option opt [Boolean] :absolute (false) is the +path+ argument absolute?
+    # @return [ERB] an instance of {http://ruby-doc.org/stdlib-1.9.3/libdoc/erb/rdoc/ERB.html ERB}
     def get_template(path, opt={})
       path += '.erb'
       fullpath = if opt[:absolute]
@@ -117,19 +104,18 @@ module Cog
       ERB.new File.read(fullpath), 0, '>'
     end
     
-    # Stamp a template +source+ onto a +destination+.
-    #
-    # ==== Arguments
-    # * +template_path+ - a path to a template file which is relative to one
-    #   of the template directories
-    # * +destination+ - a path to which the generated file should be written
-    #
-    # ==== Options
-    # * <tt>:absolute_template_path</tt> - is the +template_path+ argument absolute? (default: +false+)
-    # * <tt>:absolute_destination</tt> - is the +destination+ argument absolute? (default: +false+)
-    def stamp(template_path, destination, opt={})
+    # Stamp a template into a file or return it as a string
+    # @param template_path [String] path to template file relative one of the {Config#template_paths}
+    # @param destination [String] path to which the generated file should be written, relative to the {Config#project_source_path}
+    # @option opt [Boolean] :absolute_template_path (false) is the +template_path+ absolute?
+    # @option opt [Boolean] :absolute_destination (false) is the +destination+ absolute?
+    # @option opt [Boolean] :quiet (false) suppress writing to STDOUT?
+    # @return [nil or String] if +destination+ is not provided, the stamped template is returned as a string
+    def stamp(template_path, destination=nil, opt={})
       t = get_template template_path, :absolute => opt[:absolute_template_path]
       b = opt[:binding] || binding
+      return t.result(b) if destination.nil?
+      
       dest = opt[:absolute_destination] ? destination : File.join(Config.instance.project_source_path, destination)
       FileUtils.mkpath File.dirname(dest) unless File.exists? dest
       scratch = "#{dest}.scratch"
@@ -139,30 +125,38 @@ module Cog
       else
         updated = File.exists? dest
         FileUtils.mv scratch, dest
-        STDOUT.write "#{updated ? :Updated : :Created} #{dest}\n".color(updated ? :white : :green)
+        STDOUT.write "#{updated ? :Updated : :Created} #{dest.relative_to_project_root}\n".color(updated ? :white : :green) unless opt[:quiet]
       end
       nil
     end
 
     # Copy a file from +src+ to +dest+, but only if +dest+ does not already exist.
-    def copy_if_missing(src, dest)
+    # @param src [String] where to copy from
+    # @param dest [String] where to copy to
+    # @option opt [Boolean] :quiet (false) suppress writing to STDOUT?
+    # @return [nil]
+    def copy_if_missing(src, dest, opt={})
       unless File.exists? dest
         FileUtils.cp src, dest
-        STDOUT.write "Created #{dest}\n".color(:green)
+        STDOUT.write "Created #{dest.relative_to_project_root}\n".color(:green) unless opt[:quiet]
       end
     end
 
     # Recursively create directories in the given path if they are missing.
-    def touch_path(*path_components)
-      path = File.join path_components
+    # @param path [String] a file system path representing a directory
+    # @option opt [Boolean] :quiet (false) suppress writing to STDOUT?
+    # @return [nil]
+    def touch_path(path, opt={})
       unless File.exists? path
         FileUtils.mkdir_p path
-        STDOUT.write "Created #{path}\n".color(:green)
+        STDOUT.write "Created #{path.relative_to_project_root}\n".color(:green) unless opt[:quiet]
       end
+      nil
     end
     
     # File extension for a snippet of the given source code language.
-    # ==== Example
+    # @api unstable
+    # @example
     #   snippet_extension 'c++' # => 'h'
     def snippet_extension(lang = 'text') # :nodoc:
       case lang
@@ -172,24 +166,20 @@ module Cog
         'txt'
       end
     end
-          
-    # A warning that indicates a file is maintained by a generator
-    def generated_warning # :nodoc:
-      lang = Config.instance.language
-      t = get_template "snippets/#{lang}/generated_warning.#{snippet_extension lang}", :cog_template => true
-      t.result(binding)
-    end
-    
-    def include_guard_begin(name) # :nodoc:
+
+    # @api unstable
+    def include_guard_begin(name)
       full = "COG_INCLUDE_GUARD_#{name.upcase}"
       "#ifndef #{full}\n#define #{full}"
     end
     
-    def include_guard_end # :nodoc:
+    # @api unstable
+    def include_guard_end
       "#endif // COG_INCLUDE_GUARD_[...]"
     end
     
-    def namespace_begin(name) # :nodoc:
+    # @api unstable
+    def namespace_begin(name)
       return if name.nil?
       case Config.instance.language
       when /c\+\+/
@@ -197,7 +187,8 @@ module Cog
       end
     end
 
-    def namespace_end(name) # :nodoc:
+    # @api unstable
+    def namespace_end(name)
       return if name.nil?
       case Config.instance.language
       when /c\+\+/
@@ -206,7 +197,7 @@ module Cog
     end
     
   private
-    def same?(original, scratch) # :nodoc:
+    def same?(original, scratch)
       if File.exists? original
         File.read(original) == File.read(scratch)
       else

data/lib/cog/helpers.rb

@@ -0,0 +1 @@
+require 'cog/helpers/string'

data/lib/cog/helpers/string.rb

@@ -0,0 +1,11 @@
+require 'cog/config'
+
+class String
+  
+  # @return [String] strips {Cog::Config#project_root} from the beginning of this string
+  def relative_to_project_root
+    return unless Cog::Config.instance.project?
+    root = Cog::Config.instance.project_root
+    start_with?(root) ? slice(root.length+1..-1) : dup
+  end
+end

data/lib/cog/spec_helpers.rb

@@ -6,15 +6,17 @@ module Cog
   
   # Modules and classes to help write specs for testing +cog+
   #
-  # === Example
-  # Requiring the helpers will make extra SpecHelpers::Matchers available to
-  # your RSpec tests. These are useful for testing a SpecHelpers::Invocation,
-  # which is returned from a call to SpecHelpers::Runner#run
+  # Requiring the helpers will make extra {SpecHelpers::Matchers} available to
+  # your RSpec tests. These are useful for testing a {SpecHelpers::Invocation},
+  # which is returned from a call to {SpecHelpers::Runner#run}
   #
+  # @example
   #   require 'cog/spec_helpers'
   # 
   #   describe 'The command line interface' do
   # 
+  #     include Cog::SpecHelpers
+  #
   #     before :all do
   #       @cog = Cog::SpecHelpers::Runner.new 'bin/cog'
   #     end
@@ -22,42 +24,69 @@ module Cog
   #     it 'should print help when no args are passed' do
   #       @cog.run.should show_help
   #     end
+  #
+  #     context 'in an uninitialized project' do
+  #
+  #       before :each do
+  #         use_fixture :uninitialized
+  #       end
   # 
+  #       it 'running `cog init` should make a Cogfile' do
+  #         @cog.run(:init).should make(cogfile_path)
+  #       end
+  #
+  #     end
   #   end
   module SpecHelpers
 
-    # Absolute path to the root spec directory
+    # @return [String] absolute path to the root spec directory
     def spec_root
       File.expand_path File.join(File.dirname(__FILE__), '..', '..', 'spec')
     end
     
-    # Directory of an active spec fixture.
+    # @return [String] directory of an active spec fixture.
     def active_fixture_dir
       File.join spec_root, 'active_fixture'
     end
 
-    # Path to the Cogfile in the active spec fixture
+    # @return [String] path to the Cogfile in the active spec fixture
     def cogfile_path
       File.join active_fixture_dir, 'Cogfile'
     end
     
-    # Path to the cog directory in the active spec fixture
+    # @return [String] path to the cog directory in the active spec fixture
     def cog_directory
       File.join active_fixture_dir, 'cog'
     end
     
-    # Path to the generator with the given name
+    # @param name [String] active fixture generator identifier
+    # @return [String] path to the generator with the given name
     def generator(name)
       File.expand_path File.join(active_fixture_dir, 'cog', 'generators', "#{name}.rb")
     end
+
+    # @param name [String] template identifier (without the .erb extension)
+    # @return [String] absolute file system path to the template
+    def template(name)
+      File.expand_path File.join(active_fixture_dir, 'cog', 'templates', "#{name}")
+    end
     
-    # Path to the test tool with the given name
+    # @param name [String] tool fixture identifier
+    # @return [String] path to the test tool with the given name
     def tool(name)
       File.expand_path File.join(spec_root, 'tools', name.to_s, 'lib', "#{name}.rb")
     end
     
-    # The next cog spec will execute in a fresh copy of the given fixture directory.
+    # @param filename [String] name of a generated source file
+    # @return [String] absolute path to the generated file
+    def generated_file(filename)
+      File.expand_path File.join(active_fixture_dir, 'src', filename)
+    end
+    
+    # The next cog spec will execute in a fresh copy of the given fixture
     # Fixture directories are stored in <tt>spec/fixtures</tt>.
+    # @param name [String] name of the fixture
+    # @return [nil]
     def use_fixture(name)
       path = File.join spec_root, 'fixtures', name.to_s
       if File.exists?(path) && File.directory?(path)
@@ -67,6 +96,7 @@ module Cog
       else
         throw :invalid_fixture_name
       end
+      nil
     end
     
   end

data/lib/cog/spec_helpers/matchers.rb

@@ -4,11 +4,12 @@ require 'rspec'
 module Cog
   module SpecHelpers
     
-    # Extra should or should_not matchers for RSpec.
-    # Check out #match_maker for help writing new matchers.
+    # Extra +should+ or +should_not+ matchers for RSpec.
+    # Check out {#match_maker} for help writing new matchers.
     module Matchers
       
-      # The target Invocation should write something to STDERR, indicating an error
+      # The target {Invocation} should write something to STDERR, indicating an error
+      # @return [nil]
       def complain
         match_maker do
           message { "to [write something|not write anything] to STDERR" }
@@ -16,7 +17,9 @@ module Cog
         end
       end
 
-      # The target Invocation should create a +Cogfile+ where none existed before
+      # The target {Invocation} should create a file at the given +path+
+      # @param path [String] path to check for a file after the invocation
+      # @return [nil]
       def make(path)
         match_maker do
           message { "to [create|not create] #{path}" }
@@ -29,7 +32,8 @@ module Cog
         end
       end
       
-      # The target Invocation should do something, as determined by standard output
+      # The target {Invocation} should do something, as determined by standard output
+      # @return [nil]
       def do_something
         match_maker do
           message { "to [write something|not write anything] to STDOUT" }
@@ -37,7 +41,9 @@ module Cog
         end
       end
       
-      # The target Invocation should write the given list of lines to standard output
+      # The target {Invocation} should write the given list of lines to standard output
+      # @param x [Array<String>] a list of lines to match against standard output
+      # @return [nil]
       def output(x)
         match_maker do
           message { "to [write|not write] #{x.join "\n"} to STDOUT"}
@@ -47,7 +53,8 @@ module Cog
         end
       end
       
-      # The target Invocation should output the default help text
+      # The target {Invocation} should output the default help text
+      # @return [nil]
       def show_help
         match_maker do
           message { "to [show|not show] the default help text, got #{lines.first.inspect}" }

data/lib/cog/spec_helpers/matchers/match_maker.rb

@@ -2,8 +2,8 @@ module Cog
   module SpecHelpers
     module Matchers
       
-      # Within Matchers#match_maker blocks, +self+ is set to an instance of this
-      # class.
+      # Within {Matchers#match_maker} blocks, +self+ is set to an instance of this
+      # class
       class MatchMaker
 
         # A list of lines read from STDOUT after executing the Invocation
@@ -17,69 +17,91 @@ module Cog
         # 
         # The template is used for both positive and negative failures.
         # Substrings which look like this <tt>"[positive|negative]</tt>" will
-        # be replaced with the appropriate section. For example
+        # be replaced with the appropriate section.
+        #
+        # @example
         #   message { "to [show|not show] the default help text" }
         # 
         # would read "expected cog to show the default help text"
         # for a positive failure and "expected cog to not show the
         # default help text" for a negative failure. The "expected cog"
         # part is inserted automatically.
+        #
+        # @yield called after the invocation. {#lines} and {#error} can be used
+        # @return [nil]
         def message(&block)
           @msg_block = block
+          nil
         end
         
         # Define a block which runs before the Invocation.
         #
         # This is not required, but can be used to save context that is used
         # the in post invocation #test.
+        #
+        # @yield called before the invocation. Save context as instance variables
+        # @return [nil]
         def before(&block)
           @before_block = block
+          nil
         end
         
         # Define the test which runs after the Invocation
         #
         # This can make use of instance variables set during #before.
+        #
+        # @yield called after the invocation
+        # @return [nil]
         def test(&block)
           @test_block = block
+          nil
         end
         
-        def matches?(runner) # :nodoc:
-          @runner = runner
+        # @api developer
+        # @param invocation [Invocation] +cog+ executable and arguments bundled up
+        # @return [Boolean] result of the {#test} block
+        def matches?(invocation)
+          @invocation = invocation
           instance_eval &@before_block unless @before_block.nil?
-          @runner.exec do |input, output, error|
+          @invocation.exec do |input, output, error|
             @lines = output.readlines
             @error = error.readlines
           end
           instance_eval &@test_block
         end
-        def failure_message # :nodoc:
+
+        # @api developer
+        # @return [String] positive interpretation of the {#message} block result
+        def failure_message
           msg = instance_eval &@msg_block
           msg = msg.gsub /\[([^\|\]]*)(?:\|([^\]]*)\])?/, '\1'
-          "expected #{@runner} #{msg}\n#{trace}"
+          "expected #{@invocation} #{msg}\n#{trace}"
         end
-        def negative_failure_message # :nodoc:
+        
+        # @api developer
+        # @return [String] negative interpretation of the {#message} block result
+        def negative_failure_message
           msg = instance_eval &@msg_block
           msg = msg.gsub /\[([^\|\]]*)(?:\|([^\]]*)\])?/, '\2'
-          "expected #{@runner} #{msg}\n#{trace}"
+          "expected #{@invocation} #{msg}\n#{trace}"
         end
         
-        def trace # :nodoc
+        # @api developer
+        # @return [String] STDOUT and STDERR
+        def trace
           "STDOUT:\n#{@lines.join "\n"}\nSTDERR:\n#{@error.join "\n"}"
         end
       end
       
-      # Makes it easy to write RSpec matchers
-      #
-      # Here is how the matcher for Matchers#show_help is written using this method
-      # #match_maker method.
+      # Makes it easier to write RSpec matchers for testing +cog+ command invocations
+      # @yield +self+ is set to an instance of {MatchMaker}
+      # @example
       #   def show_help
       #     match_maker do
       #       message { "to [show|not show] the default help text, got #{lines.first.inspect}" }
       #       test { (/help.*code gen/ =~ lines[1]) }
       #     end
       #   end
-      #
-      # Within the +match_maker+ block, +self+ is set to an instance of MatchMaker.
       def match_maker(&block)
         m = MatchMaker.new
         m.instance_eval &block

data/lib/cog/spec_helpers/runner.rb

@@ -9,16 +9,15 @@ module Cog
       # Value of the COG_TOOLS environment variable for invocations returned from #run
       attr_accessor :tools
       
+      # @param path_to_cl_app [String] path 
       def initialize(path_to_cl_app)
         @cog = File.expand_path path_to_cl_app
         @tools = []
       end
 
       # Run cog with the given arguments
-      #
-      # === Returns
-      # An instance of Invocation configured with the arguments. Use should and
-      # should_not with the custom Matchers
+      # @param args [Array<String>] arguments to pass to +cog+
+      # @return [Invocation] an object which can be used with custom {Matchers}
       def run(*args)
         args = [@cog] + args
         Invocation.new(args.collect {|x| x.to_s}, :tools => @tools)
@@ -26,16 +25,23 @@ module Cog
     end
     
     # Represents a +cog+ command line invocation, which can be tested with
-    # +RSpec+ +should+ and +should_not+ custom Matchers. This is the kind of
-    # object returned by Runner#run.
+    # +RSpec+ +should+ and +should_not+ custom {Matchers}. This is the kind of
+    # object returned by {Runner#run}.
     class Invocation
       
-      def initialize(cmd, opt={}) # :nodoc:
+      # @api developer
+      # @param cmd [Array<String>] path to +cog+ executable and arguments
+      # @option opt [Array<String>] :tools ([]) a list of tools to add to the +COG_TOOLS+ environment variable just before running the command with {#exec}
+      def initialize(cmd, opt={})
         @cmd = cmd
-        @tools = opt[:tools].join ':'
+        @tools = (opt[:tools] || []).join ':'
       end
       
-      def exec(*args, &block) # :nodoc:
+      # Execute the command
+      # @api developer
+      # @yield [stdin, stdout, stderr] standard pipes for the invocation
+      # @return [nil]
+      def exec(&block)
         @cmd = ['bundle', 'exec'] + @cmd
         ENV['COG_TOOLS'] = @tools
         Open3.popen3 *@cmd do |i,o,e,t|
@@ -43,7 +49,9 @@ module Cog
         end
       end
 
-      def to_s # :nodoc:
+      # @api developer
+      # @return [String] loggable representation
+      def to_s
         "`COG_TOOLS=#{@tools} #{@cmd.compact.join ' '}`"
       end
     end

data/lib/cog/tool.rb

@@ -4,10 +4,12 @@ require 'rainbow'
 
 module Cog
   
-  # For more details on writing tools see https://github.com/ktonon/cog#tools
+  # @see https://github.com/ktonon/cog#tools Introduction to Tools
   class Tool
 
     # A list of available tools
+    # @param verbose [Boolean] should full paths be listed for tools which are explicitly referenced?
+    # @return [Array<String>] a list of strings which can be passed to +require+
     def self.list(verbose=false)
       x = (ENV['COG_TOOLS'] || '').split ':'
       if x.all? {|path| path.slice(-3..-1) != '.rb' || File.exists?(path)}
@@ -29,9 +31,8 @@ module Cog
     end
     
     # Generate a new tool with the given name
-    #
-    # ==== Returns
-    # Whether or not the generator was created successfully
+    # @param name [String] name of the tool to create. Should not conflict with other tool names
+    # @return [Boolean] was the tool created successfully?
     def self.create(name)
       if File.exists? name
         STDERR.write "A #{File.directory?(name) ? :directory : :file} named '#{name}' already exists\n".color(:red)
@@ -62,9 +63,8 @@ module Cog
     end
 
     # Find an available tool with the given name
-    #
-    # ==== Returns
-    # A fully qualified tool path, which can be required
+    # @param name [String] name of the tool to search for
+    # @return [String] a fully qualified tool path, which can be passed to +require+
     def self.find(name)
       x = (ENV['COG_TOOLS'] || '').split ':'
       x.each do |path|

data/lib/cog/version.rb

@@ -1,3 +1,5 @@
 module Cog
-  VERSION = '0.0.19' unless const_defined? :VERSION
+  unless const_defined? :VERSION
+    VERSION = '0.0.20'
+  end
 end

data/yard-templates/default/fulldoc/html/css/common.css

@@ -0,0 +1,6 @@
+#toc {
+  -webkit-box-shadow: 0px 0px 2px #bbb;
+}
+#search a:link, #search a:visited {
+  -webkit-box-shadow: 0px 0px 2px #eee;
+}

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cog
 version: !ruby/object:Gem::Version 
-  hash: 57
+  hash: 55
   prerelease: 
   segments: 
   - 0
   - 0
-  - 19
-  version: 0.0.19
+  - 20
+  version: 0.0.20
 platform: ruby
 authors: 
 - Kevin Tonon
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-11-05 00:00:00 Z
+date: 2012-11-07 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: gli
@@ -60,7 +60,7 @@ dependencies:
   type: :development
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: rdoc
+  name: yard
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
@@ -79,16 +79,14 @@ executables:
 - cog
 extensions: []
 
-extra_rdoc_files: 
-- API.rdoc
+extra_rdoc_files: []
+
 files: 
 - bin/cog
 - Default.cogfile
 - LICENSE
 - templates/cog/generator/basic-template.txt.erb.erb
 - templates/cog/generator/basic.rb.erb
-- templates/cog/snippets/c++/generated_warning.h.erb
-- templates/cog/snippets/generated_warning.txt
 - templates/cog/tool/API.rdoc.erb
 - templates/cog/tool/Gemfile.erb
 - templates/cog/tool/generator.rb.erb.erb
@@ -99,10 +97,13 @@ files:
 - templates/cog/tool/tool.gemspec.erb
 - templates/cog/tool/tool.rb.erb
 - templates/cog/tool/version.rb.erb
+- templates/warning.h.erb
 - lib/cog/config/cogfile.rb
 - lib/cog/config.rb
 - lib/cog/errors.rb
 - lib/cog/generator.rb
+- lib/cog/helpers/string.rb
+- lib/cog/helpers.rb
 - lib/cog/spec_helpers/matchers/match_maker.rb
 - lib/cog/spec_helpers/matchers.rb
 - lib/cog/spec_helpers/runner.rb
@@ -110,17 +111,13 @@ files:
 - lib/cog/tool.rb
 - lib/cog/version.rb
 - lib/cog.rb
-- API.rdoc
+- yard-templates/default/fulldoc/html/css/common.css
 homepage: https://github.com/ktonon/cog
 licenses: []
 
 post_install_message: 
-rdoc_options: 
-- --title
-- cog
-- --main
-- cog.rdoc
-- -ri
+rdoc_options: []
+
 require_paths: 
 - lib
 - lib

data/API.rdoc

@@ -1,6 +0,0 @@
-= cog API Docs
-
-+cog+ is a command line tool which helps you write code generators.
-
-This is the API docs. For a more general introduction to +cog+ visit
-https://github.com/ktonon/cog#readme

data/templates/cog/snippets/generated_warning.txt

@@ -1,7 +0,0 @@
-WARNING
-
-This is a generated file. DO NOT EDIT THIS FILE! Your changes will be lost
-the next time this file is regenerated.
-
-This file was generating using cog
-https://github.com/ktonon/cog