rookie 0.2.1 → 0.3.0

data/README.markdown

@@ -2,11 +2,23 @@
 
 Simple Rake tasks that make life easier.
 
+# Installation
+
+Latest version:
+
+    gem install rookie
+
+From source:
+
+    git clone git://github.com/matheusmoreira/rookie.git
+
+# Introduction
+
 Putting this in your `Rakefile`:
 
     require 'rookie'
 
-    Rookie::Tasks.new 'simple.gemspec'
+    Rookie::Tasks.new('simple.gemspec').define_tasks!
 
 Gets you a whole set of nice commands to work with your gem. Run `rake -T` for
 details.

data/Rakefile

@@ -1,3 +1,3 @@
 require 'rookie'
 
-Rookie::Tasks.new 'rookie.gemspec'
+Rookie::Tasks.new('rookie.gemspec').define_tasks!

data/lib/rookie.rb

@@ -1,2 +1,6 @@
+# A collection of Rake tasks.
+module Rookie
+end
+
 require 'rookie/tasks'
 require 'rookie/version'

data/lib/rookie/tasks.rb

@@ -4,31 +4,50 @@ require 'rookie/tasks/git'
 require 'rake/tasklib'
 
 module Rookie
+
+  # Provides many useful tasks, like the Gem, Git and Console tasks.
+  #
+  # Don't forget to call #define_tasks! after creating an instance of this
+  # class!
   class Tasks < ::Rake::TaskLib
 
-    attr_accessor :gem, :git, :console
+    # The Gem task.
+    attr_accessor :gem
+
+    # The Git task.
+    attr_accessor :git
+
+    # The Console task.
+    attr_accessor :console
 
-    def initialize(gemspec = nil, opts = {})
+    # Initializes the tasks with the given gem specification and options.
+    #
+    # Yields the new instance if given a block.
+    def initialize(gemspec, opts = {})
       self.gem = Tasks::Gem.new gemspec
       self.git = Tasks::Git.new gem.spec.version.to_s
       self.console = Tasks::Console.new gem.spec, opts
       yield self if block_given?
-      define
     end
 
-    def define
+    # Defines the tasks for all initialized (not +nil+) tasks.
+    def define_tasks!
       setup_tasks, clean_tasks, release_tasks = [], [], []
 
       if git
+        git.define_tasks!
         release_tasks << 'git:release'
       end
 
       if gem
+        gem.define_tasks!
         setup_tasks << 'gem:setup'
         clean_tasks << 'gem:clean'
         release_tasks << 'gem:release'
       end
 
+      console.define_tasks! if console
+
       desc 'Setup project'
       task :setup => setup_tasks
 
@@ -42,4 +61,5 @@ module Rookie
     end
 
   end
+
 end

data/lib/rookie/tasks/console.rb

@@ -2,32 +2,59 @@ require 'rake/tasklib'
 
 module Rookie
   class Tasks < ::Rake::TaskLib
+
+    # This task provides an easy way to interactively test your gem by
+    # automatically loading and requiring it in an interactive ruby session.
     class Console < ::Rake::TaskLib
 
-      attr_accessor :spec, :program
+      # The gem specification.
+      attr_accessor :spec
+
+      # The name of the program to invoke.
+      attr_accessor :program
+
+      # The full command to execute.
       attr_writer :command
 
+      # Unless set explicitly, will be automatically generated from the #program
+      # name and gem specification.
       def command
         @command ||= generate_command_string
       end
 
+      # Creates a new console task with the given parameters. Options may
+      # specify:
+      #
+      # [:program]  the name of the program to invoke; +irb+ by default.
+      # [:command]  the full command to execute. Use if the command you want to
+      #             run doesn't take the <tt>-I</tt> and <tt>-r</tt> command
+      #             line arguments.
+      #
+      # Yields the instance if given a block.
+      #
+      # Tasks do not get defined automatically; don't forget to call
+      # #define_tasks!
       def initialize(spec, opts = {})
         self.spec = spec
-        self.program = opts.fetch :program, 'irb'
+        self.program = opts.fetch :program, :irb
         self.command = opts.fetch :command, nil
         yield self if block_given?
-        define
       end
 
-      def define
-        desc 'Starts an interactive ruby session with your gem loaded'
+      # Defines the console task.
+      def define_tasks!
+        desc 'Starts an interactive ruby session with the gem loaded'
         task :console do
           sh command
         end
       end
 
+      # Generates a command string from this task's #program name and gem
+      # specification. For example:
+      #
+      #   irb -I lib -r gem_name
       def generate_command_string
-        program.dup.tap do |command_string|
+        program.to_s.dup.tap do |command_string|
           spec.require_paths.each do |path|
             command_string << ' -I ' << path
           end
@@ -36,5 +63,6 @@ module Rookie
       end
 
     end
+
   end
 end

data/lib/rookie/tasks/gem.rb

@@ -1,54 +1,84 @@
-require 'rake/tasklib'
 require 'fileutils'
+require 'rake/tasklib'
 
 module Rookie
   class Tasks < ::Rake::TaskLib
+
+    # Adds various gem management tasks that allows you to build, install,
+    # uninstall and release your gem with ease.
     class Gem < ::Rake::TaskLib
 
-      attr_reader :spec, :dir
+      # The gem specification.
+      attr_reader :spec
 
+      # The directory where <tt>.gem</tt> files will be stored. <tt>'gem'</tt>
+      # by default.
+      #
+      # This directory will be completely erased by the +clean+ task. Make sure
+      # it is not in use!
+      attr_reader :dir
+
+      # Sets this task's gem specification. Loads it from a file if given a
+      # string.
       def spec=(gemspec)
         @spec = case gemspec
-          when ::Gem::Specification
-            gemspec
-          when String
-            ::Gem::Specification.load gemspec if gemspec and File.readable? gemspec
-          else
-            nil
+          when ::Gem::Specification then gemspec
+          when String then ::Gem::Specification.load gemspec if File.readable? gemspec
+          else nil
         end
       end
 
+      # The directory where packaged gems will be stored. Always relative to the
+      # current directory.
+      #
+      # This directory will be completely erased by the +clean+ task. Make sure
+      # it is not in use!
       def dir=(dir)
         @dir = File.expand_path File.join(Dir.pwd, dir)
       end
 
+      # Creates a new gem task with the given gem specification and temporary
+      # gem directory.
+      #
+      # Tasks do not get defined automatically; don't forget to call
+      # #define_tasks!
       def initialize(gemspec = nil, gem_dir = 'gem')
         self.spec = gemspec
         self.dir = gem_dir
         yield self if block_given?
-        define
       end
 
+      # The name of the packaged gem file.
+      def gem_file_name
+        "#{spec.name}-#{spec.version}.gem"
+      end
+
+      # The full path to the gem file.
       def gem_file
-        File.join dir, "#{spec.name}-#{spec.version}.gem"
+        File.join dir, gem_file_name
       end
 
+      # Builds the gem from the specification and moves it to the gem directory.
       def build_gem
         FileUtils.mkdir_p dir
         gem = ::Gem::Builder.new(spec).build
         FileUtils.mv gem, dir
       end
 
+      # Executes a gem command.
       def gem(cmd, arg = gem_file)
         "gem #{cmd} #{arg}"
       end
 
+      # Removes the gem directory.
       def clean!
         FileUtils.rm_rf dir
       end
 
-      def define
+      # Defines the gem tasks.
+      def define_tasks!
         directory dir
+
         namespace :gem do
           desc 'Builds the gem from the specification'
           task :build => dir do
@@ -60,7 +90,7 @@ module Rookie
             sh gem :push
           end
 
-          desc 'Same as gem:release'
+          desc 'Same as gem:push'
           task :release => :push
 
           desc 'Installs the gem locally'
@@ -81,10 +111,12 @@ module Rookie
           desc 'Installs the gem locally and cleans up'
           task :setup => [ :install, :clean ]
         end
+
         desc 'Same as gem:build'
         task :gem => 'gem:build'
       end
 
     end
+
   end
 end

data/lib/rookie/tasks/git.rb

@@ -4,29 +4,49 @@ require 'rake/tasklib'
 
 module Rookie
   class Tasks < ::Rake::TaskLib
+
+    # This task provides a way to quickly and easily release git projects using
+    # a gem specification.
     class Git < ::Rake::TaskLib
 
-      attr_accessor :release_version, :working_directory
+      # The version the project will be released under.
+      attr_accessor :release_version
+
+      # Directory which contains the git repository.
+      attr_accessor :working_directory
+
+      # Logger which will be used to log the git messages. Logs to SDTOUT by
+      # default.
       attr_writer :logger
 
+      # Lazily created logger.
       def logger
         @logger ||= create_logger
       end
 
+      # Creates a new git task with the given parameters. Yields the instance
+      # if given a block.
+      #
+      # Tasks do not get defined automatically; don't forget to call
+      # #define_tasks!
       def initialize(release_version = nil, working_dir = Dir.pwd, logger = nil)
         self.logger = logger
         self.working_directory = working_dir
         self.release_version = release_version
         yield self if block_given?
-        define
       end
 
+      # Computes a release tag for the given version.
       def release_tag(version = release_version)
-        "v#{version.to_s}"
+        "v#{version}"
       end
 
+      # Tags the latest commit in the repository with the given tag name.
+      #
+      # If the tag is invalid or already in the repository, an error will be
+      # raised prior to tagging.
       def tag!(tag_name)
-        raise "Tag '#{tag_name.inspect}' is invalid" if tag_name.nil? or tag_name.empty?
+        raise "Tag '#{tag_name}' is invalid" if tag_name.nil? or tag_name.empty?
         if already_tagged? tag_name
           raise "Tag '#{tag_name}' already in repository"
         else
@@ -34,20 +54,29 @@ module Rookie
         end
       end
 
+      # Pushes the changes in the given branch to the given remote repository.
+      #
+      # Tags will be pushed too if +tags+ is +true+.
       def push!(remote = 'origin', branch = 'master', tags = false)
         git.push remote, branch, tags
       end
 
+      # Tags the latest commit with the given version tag and pushes the given
+      # branch to the given remote repository, including tags.
       def release!(version_tag = release_tag, remote = 'origin', branch = 'master')
         tag! version_tag
         push! remote, branch, true
       end
 
+      # Returns whether the repository already contains the given tag name.
       def already_tagged?(tag_name)
-        git.tag tag_name rescue nil
+        git.tag tag_name
+      rescue ::Git::GitTagNameDoesNotExist
+        false
       end
 
-      def define
+      # Defines the git tasks.
+      def define_tasks!
         namespace :git do
           desc 'Tags latest commit with the given tag name'
           task :tag, :tag_name do |task, args|
@@ -78,10 +107,12 @@ module Rookie
 
       protected
 
+      # Lazily created git handle. Uses the logger returned by #logger.
       def git
         @git ||= ::Git.open working_directory, :log => logger
       end
 
+      # Creates a logger to STDOUT at INFO level with a custom formatter.
       def create_logger
         ::Logger.new(STDOUT).tap do |logger|
           logger.level = ::Logger::INFO
@@ -90,5 +121,6 @@ module Rookie
       end
 
     end
+
   end
 end

data/lib/rookie/version.rb

@@ -1,12 +1,32 @@
 module Rookie
+
+  # Rookie's version.
   module Version
 
+    # Major version.
+    #
+    # Increments denote backward-incompatible changes and additions.
     MAJOR = 0
-    MINOR = 2
-    PATCH = 1
+
+    # Minor version.
+    #
+    # Increments denote backward-compatible changes and additions.
+    MINOR = 3
+
+    # Patch version.
+    #
+    # Increments denote changes in implementation.
+    PATCH = 0
+
+    # Build version.
+    #
+    # Used for pre-release versions.
     BUILD = nil
 
+    # Complete version string, which is every individual version number joined
+    # by a dot (<tt>'.'</tt>), in descending order of prescedence.
     STRING = [ MAJOR, MINOR, PATCH, BUILD ].compact.join '.'
 
   end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rookie
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-30 00:00:00.000000000 Z
+date: 2012-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &14547320 !ruby/object:Gem::Requirement
+  requirement: &12451360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *14547320
+  version_requirements: *12451360
 - !ruby/object:Gem::Dependency
   name: git
-  requirement: &14550400 !ruby/object:Gem::Requirement
+  requirement: &12453220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *14550400
+  version_requirements: *12453220
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &14553060 !ruby/object:Gem::Requirement
+  requirement: &12455200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *14553060
+  version_requirements: *12455200
 description: Simple Rake tasks that make life easier.
 email: matheus.a.m.moreira@gmail.com
 executables: []
@@ -78,7 +78,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4064470574437623325
+      hash: -1447020639505331606
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -87,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4064470574437623325
+      hash: -1447020639505331606
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10