wright 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a6ea11aed95157e957a5d973bbf12e34cb868ace
-  data.tar.gz: 4bcb75ed67ab7f90027fe7a621b0f240c6a8c7fb
+  metadata.gz: 0005b749e54ff7904188cbd497f1757c460c0b4d
+  data.tar.gz: b1fc596dc236a11f9a18c9de89823c91f0d20fee
 SHA512:
-  metadata.gz: 0c5b952723832faf165f63ccdccd3e46cd9bce20b37a7092bc88bdb478f766bc3ab2684bba85f0633f61f152f4908a9726590b160263ab7c01f1cd97046fe653
-  data.tar.gz: 02971bb7a151b4a15712177fd70306a87cb4adad83faa69e1b3900a5b1462513099c152b9d542cf983bc4c297c62c896d2eba60017884b9f2d222687baf28d45
+  metadata.gz: d9eaae5610049c8407782fd8089f789a9dbbe7208d08a46f5de4e8618b258824830c653f18c59bb0175d83b5d5661d90c276996fed278ebaa223ffce7748a706
+  data.tar.gz: 0975e81800682d9e93ec0d365f20ef9a4effdab230c217b2b6661eb2ffc8e1ed7d2e1ec39933f30f46795c5a42ce01343eab154bb104e3009558ceb52552abc5

data/NEWS

@@ -1,4 +1,9 @@
 * wright NEWS
+** 0.1.2 (2015-01-31)
+
+ - Convert docs to YARD
+ - Fix color code for warnings
+
 ** 0.1.1 (2015-01-20)
 
  - Remove hardcoded package provider config

data/README.md

@@ -1,3 +1,6 @@
+wright
+======
+
 [![Gem Version](http://img.shields.io/gem/v/wright.svg?style=flat-square)][gem]
 [![Build Status](http://img.shields.io/travis/sometimesfood/wright.svg?style=flat-square)][travis]
 [![Code Climate](http://img.shields.io/codeclimate/github/sometimesfood/wright.svg?style=flat-square)][codeclimate]
@@ -6,9 +9,6 @@
 [travis]: https://travis-ci.org/sometimesfood/wright
 [codeclimate]: https://codeclimate.com/github/sometimesfood/wright
 
-wright
-======
-
 Lightweight configuration management.
 
 Requirements

data/Rakefile

@@ -1,21 +1,7 @@
 #!/usr/bin/env rake
 require 'bundler/gem_tasks'
 require 'rake/testtask'
-require 'rdoc/task'
 
 Rake::TestTask.new do |t|
   t.pattern = 'spec/**/*_spec.rb'
 end
-
-RDoc::Task.new(clobber_rdoc: 'rdoc:clobber',
-               rerdoc: 'rdoc:force') do |t|
-  t.rdoc_files.include('lib/**/*.rb')
-  t.options << '--markup=tomdoc'
-end
-
-namespace :rdoc do
-  desc 'Show RDoc coverage report'
-  task :coverage do
-    exec 'rdoc --markup=tomdoc --coverage-report lib/'
-  end
-end

data/lib/wright.rb

@@ -8,6 +8,7 @@ require 'wright/resource/file'
 require 'wright/resource/package'
 require 'wright/resource/symlink'
 
-# Public: TODO: Add some documentation
+# @todo add proper documentation
+# Lightweight configuration management.
 module Wright
 end

data/lib/wright/config.rb

@@ -1,13 +1,12 @@
 require 'forwardable'
 
 module Wright
-  # Public: Configuration container, wraps a regular Ruby hash.
+  # Configuration container, wraps a regular Ruby hash.
   #
   # Useful for getting and setting configuration values, such as
-  # logging verbosity, colour output and provider configuration.
-  #
-  # Examples
+  # logging verbosity, color output and provider configuration.
   #
+  # @example
   #   Wright::Config[:foo] = { bar: :baz }
   #   Wright::Config[:foo][:bar]
   #   # => :baz
@@ -19,12 +18,11 @@ module Wright
     end
     private_class_method :new
 
-    # Public: Check if a (nested) configuration value is set.
-    #
-    # path - The configuration item as an argument list.
+    # Checks if a (nested) configuration value is set.
     #
-    # Examples
+    # @param path [Array<Symbol>] the configuration key
     #
+    # @example
     #   Wright::Config[:foo] = { bar: :baz }
     #   Wright::Config.nested_key?(:foo, :bar)
     #   # => true
@@ -32,7 +30,7 @@ module Wright
     #   Wright::Config.nested_key?(:this, :doesnt, :exist)
     #   # => false
     #
-    # Returns true if the configuration value is set and false
+    # @return [Bool] true if the configuration value is set and false
     #   otherwise.
     def self.nested_key?(*path)
       last_key = path.pop
@@ -43,12 +41,11 @@ module Wright
       last_hash.respond_to?(:key?) && last_hash.key?(last_key)
     end
 
-    # Public: Retrieve a (nested) configuration value.
-    #
-    # path - The configuration item as an argument list.
+    # Retrieves a (nested) configuration value.
     #
-    # Examples
+    # @param path [Array<Symbol>] the configuration key
     #
+    # @example
     #   Wright::Config[:foo] = { bar: :baz }
     #   Wright::Config.nested_value(:foo, :bar)
     #   # => :baz
@@ -56,7 +53,7 @@ module Wright
     #   Wright::Config.nested_value(:this, :doesnt, :exist)
     #   # => nil
     #
-    # Returns the configuration value or nil if the value is not set.
+    # @return the configuration value or nil if the value is not set
     def self.nested_value(*path)
       nested_key?(*path) ? path.reduce(@config_hash) { |a, e| a[e] } : nil
     end

data/lib/wright/dry_run.rb

@@ -1,28 +1,27 @@
 module Wright # rubocop:disable Documentation
   @dry_run = false
 
-  # Public: Checks if dry-run mode is currently active.
-  #
-  # Examples
+  # Checks if dry-run mode is currently active.
   #
+  # @example
   #   puts 'Just a dry-run...' if Wright.dry_run?
   #
-  # Returns true if dry-run mode is currently active and false otherwise.
+  # @return [Bool] true if dry-run mode is currently active and false
+  #   otherwise
   def self.dry_run?
     @dry_run
   end
 
-  # Public: Runs a block in dry-run mode.
-  #
-  # Examples
+  # Runs a block in dry-run mode.
   #
+  # @example
   #   Wright.dry_run do
   #     symlink '/tmp/fstab' do |s|
   #       s.to = '/etc/fstab'
   #     end
   #   end
   #
-  # Returns the block's return value.
+  # @return the block's return value
   def self.dry_run
     saved_dry_run = @dry_run
     @dry_run = true

data/lib/wright/dsl.rb

@@ -1,12 +1,11 @@
 require 'wright/util'
 
 module Wright
-  # Public: Includable Wright script DSL.
+  # Includable Wright script DSL.
   #
   # Contains resource methods for all registered resources.
   #
-  # Examples
-  #
+  # @example
   #   # define a new resource at runtime
   #   class KitchenSink < Wright::Resource; end
   #
@@ -28,16 +27,17 @@ module Wright
   #   a_sink_to_remember.class
   #   # => KitchenSink
   module DSL
-    # Public: Register a class as a resource.
+    # Registers a class as a resource.
     #
     # Creates a resource method in the DSL module. Uses the
     # snake-cased class name as method name.
     #
-    # resource_class - The resource class. Usually a subclass of
-    #                  Wright::Resource. Will be initialized with the
-    #                  resource's name as an argument.
+    # Typically resource_class is a subclass of {Resource}. It is
+    # initialized with the resource's name as an argument.
+    #
+    # @param resource_class the resource class
     #
-    # Returns nothing.
+    # @return [void]
     def self.register_resource(resource_class)
       method_name = Util.class_to_resource_name(resource_class)
       this_module = self
@@ -46,13 +46,15 @@ module Wright
       end
     end
 
-    # Internal: Instantiate a resource_class object and perform its
-    # default action.
+    # @api private
+    # Instantiates a resource and performs its default action.
     #
     # Implicitly invoking a block from within another block does not
     # work: http://blog.sidu.in/2007/11/ruby-blocks-gotchas.html
     #
-    # Returns nothing.
+    # @yield [resource] the resource
+    #
+    # @return [void]
     def self.yield_resource(resource_class, name)
       r = resource_class.new(name)
       yield(r) if block_given?

data/lib/wright/logger.rb

@@ -4,18 +4,20 @@ require 'wright/config'
 require 'wright/util/color'
 
 module Wright # rubocop:disable Documentation
-  # Public: Default logger for Wright.
+  # Default logger for Wright.
   class Logger < ::Logger
-    # Public: Default formatter for Wright log messages.
+    # @api private
+    # Default formatter for Wright log messages.
     class Formatter < ::Logger::Formatter
-      # Internal: Called by Wright::Logger to format log messages.
+      # This method is called by {Wright::Logger} to format log
+      # messages.
       #
-      # severity - The String log severity.
-      # time     - The time for the log entry. Ignored.
-      # progname - The program name for the log entry. Ignored.
-      # message  - The actual log message.
+      # @param severity [String] the log entry's severity
+      # @param _time [Time] the log entry's time stamp (ignored)
+      # @param _progname [String] the log entry's program name (ignored)
+      # @param message [String] the log message
       #
-      # Returns the formatted String log entry.
+      # @return [String] the formatted log entry
       def call(severity, _time, _progname, message)
         log_entry = "#{severity}: #{message}\n"
         if Wright::Config[:log][:colorize]
@@ -27,13 +29,12 @@ module Wright # rubocop:disable Documentation
 
       private
 
-      # Internal: ANSI-Colorize a log message according to its
-      # severity.
+      # ANSI-Colorizes a log message according to its severity.
       #
-      # string   - The String log message to be colorized.
-      # severity - The String severity of the log message.
+      # @param string [String] the log message to be colorized
+      # @param severity [String] the severity of the log message
       #
-      # Returns the colorized String.
+      # @return [String] the colorized log message
       def colorize(string, severity)
         case severity
         when 'ERROR', 'FATAL'
@@ -48,12 +49,12 @@ module Wright # rubocop:disable Documentation
       end
     end
 
-    # Public: Initialize a Logger.
+    # Initializes a Logger.
     #
     # Enables log colorization if the log device is a TTY and
     # colorization was not disabled before initialization.
     #
-    # logdev - The log device used by the Logger.
+    # @param logdev [IO] the log device used by the Logger.
     def initialize(logdev = $stdout)
       super
       Wright::Config[:log] ||= {}
@@ -64,7 +65,7 @@ module Wright # rubocop:disable Documentation
   end
 
   class << self
-    # Public: Get/Set Wright's Logger.
+    # @return [Logger] the logger used by Wright
     attr_accessor :log
   end
   @log = Wright::Logger.new

data/lib/wright/provider.rb

@@ -2,26 +2,26 @@ require 'wright/config'
 require 'wright/util/recursive_autoloader'
 
 module Wright
-  # Public: Provider class.
+  # Provider class.
   class Provider
-    # Public: Wright standard provider directory.
+    # Wright standard provider directory
     PROVIDER_DIR = File.expand_path('provider', File.dirname(__FILE__))
 
     Wright::Util::RecursiveAutoloader.add_autoloads(PROVIDER_DIR, name)
 
-    # Public: Initialize a Provider.
+    # Initializes a Provider.
     #
-    # resource - The resource used by the provider, typically a
-    #            Wright::Resource.
+    # @param resource [Resource] the resource used by the provider
     def initialize(resource)
       @resource = resource
       @updated = false
     end
 
-    # Public: Checks if the provider was updated since the last call
-    # to updated?.
+    # Checks if the provider was updated since the last call to
+    # {#updated?}
     #
-    # Returns true if the provider was updated and false otherwise.
+    # @return [Bool] true if the provider was updated and false
+    #   otherwise
     def updated?
       updated = @updated
       @updated = false

data/lib/wright/provider/directory.rb

@@ -6,11 +6,11 @@ require 'wright/util/file_permissions'
 
 module Wright
   class Provider
-    # Public: Directory provider. Used as a Provider for Resource::Directory.
+    # Directory provider. Used as a provider for {Resource::Directory}.
     class Directory < Wright::Provider
-      # Public: Create or update the directory.
+      # Creates or updates the directory.
       #
-      # Returns nothing.
+      # @return [void]
       def create
         if ::File.directory?(dirname) && permissions.uptodate?
           Wright.log.debug "directory already created: '#{@resource.name}'"
@@ -22,9 +22,9 @@ module Wright
         @updated = true
       end
 
-      # Public: Remove the directory.
+      # Removes the directory.
       #
-      # Returns nothing.
+      # @return [void]
       def remove
         if ::File.exist?(dirname) && !::File.directory?(dirname)
           fail "'#{dirname}' exists but is not a directory"

data/lib/wright/provider/file.rb

@@ -8,11 +8,11 @@ require 'tmpdir'
 
 module Wright
   class Provider
-    # Public: File provider. Used as a Provider for Resource::File.
+    # File provider. Used as a provider for {Resource::File}.
     class File < Wright::Provider
-      # Public: Create or update the File.
+      # Creates or updates the file.
       #
-      # Returns nothing.
+      # @return [void]
       def create
         fail Errno::EISDIR, filename if ::File.directory?(filename)
 
@@ -25,9 +25,9 @@ module Wright
         @updated = true
       end
 
-      # Public: Remove the File.
+      # Removes the file.
       #
-      # Returns nothing.
+      # @return [void]
       def remove
         fail Errno::EISDIR, filename if ::File.directory?(filename)
 

data/lib/wright/provider/package.rb

@@ -2,19 +2,20 @@ require 'wright/provider'
 
 module Wright
   class Provider
-    # Public: Package provider. Used as a Provider base class for
-    # Resource::Package.
+    # Package provider. Used as a base class for Resource::Package
+    # providers.
     class Package < Wright::Provider
       private
 
-      # Public: Check if the package is up-to-date for a given
-      # action.
+      # @api public
+      # Checks if the package is up-to-date for a given action.
       #
-      # action - The action symbol. Currently supports :install and
-      #          :remove.
+      # @param action [Symbol] the action. Currently supports
+      #   +:install+ and +:remove+.
       #
-      # Returns true if the package is up-to-date and false otherwise.
-      # Raises ArgumentError if the action is invalid.
+      # @return [Bool] +true+ if the package is up-to-date and +false+
+      #   otherwise
+      # @raise [ArgumentError] if the action is invalid
       def uptodate?(action)
         case action
         when :install

data/lib/wright/provider/package/apt.rb

@@ -7,12 +7,10 @@ require 'wright/provider/package'
 module Wright
   class Provider
     class Package
-      # Public: AptPackage provider. Used as a Provider for
-      # Resource::Package on Debian-based systems.
+      # Apt package provider. Used as a Provider for
+      # {Resource::Package} on Debian-based systems.
       class Apt < Wright::Provider::Package
-        # Public: Get the installed package version.
-        #
-        # Returns an array of installed package version Strings.
+        # @return [Array<String>] the installed package versions
         def installed_versions
           cmd = "dpkg-query -s #{@resource.name}"
           cmd_stdout, _cmd_stderr, cmd_status = Open3.capture3(env, cmd)
@@ -26,9 +24,9 @@ module Wright
           end
         end
 
-        # Public: Install the package.
+        # Installs the package.
         #
-        # Returns nothing.
+        # @return [void]
         def install
           if uptodate?(:install)
             Wright.log.debug "package already installed: '#{@resource.name}'"
@@ -39,9 +37,9 @@ module Wright
           @updated = true
         end
 
-        # Public: Remove the package.
+        # Removes the package.
         #
-        # Returns nothing.
+        # @return [void]
         def remove
           if uptodate?(:remove)
             Wright.log.debug "package already removed: '#{@resource.name}'"