wright 0.1.1 → 0.1.2

data/lib/wright/util/color.rb

@@ -1,49 +1,48 @@
 module Wright
   module Util
-    # Internal: ANSI color helpers.
+    # ANSI color helpers.
     module Color
-      # Internal: Colorize a string (red).
+      # Colorizes a string (red).
       #
-      # string - The string to colorize.
+      # @param string [String] the string to colorize
       #
-      # Returns the colorized String.
+      # @return [String] the colorized string
       def self.red(string)
         colorize(string, :red)
       end
 
-      # Internal: Colorize a string (yellow).
+      # Colorizes a string (yellow).
       #
-      # string - The string to colorize.
+      # @param string [String] the string to colorize
       #
-      # Returns the colorized String.
+      # @return [String] the colorized string
       def self.yellow(string)
         colorize(string, :yellow)
       end
 
-      # Internal: Colorize a string.
+      # Colorizes a string.
       #
-      # string - The string to colorize.
-      # color - The color that should be used.
-      #
-      # Examples
+      # @param string [String] the string to colorize
+      # @param color [String] the color that should be used
       #
+      # @example
       #   Wright::Util::Color.colorize('Hello world', :red)
       #   # => "\e[31mHello world\e[0m"
       #
       #   Wright::Util::Color.colorize('Hello world', :yellow)
       #   # => "\e[32mHello world\e[0m"
       #
-      # Returns the colorized String.
+      # @return [String] the colorized string
       def self.colorize(string, color)
         no_color = COLOR_MAP[:none]
         color = COLOR_MAP.fetch(color, no_color)
         "#{color}#{string}#{no_color}"
       end
 
-      COLOR_MAP = { #:nodoc:
+      COLOR_MAP = {
         none: "\e[0m",
         red: "\e[31m",
-        yellow: "\e[32m"
+        yellow: "\e[33m"
       }
       private_constant :COLOR_MAP
     end

data/lib/wright/util/file.rb

@@ -27,11 +27,11 @@
 #   OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 #   SUCH DAMAGE.
 
-module Wright #:nodoc:
+module Wright
   module Util
-    # Internal: Various file methods.
+    # Various file methods.
     module File
-      USER_MAP = { #:nodoc:
+      USER_MAP = {
         'u' => 04700,
         'g' => 02070,
         'o' => 01007,
@@ -44,7 +44,7 @@ module Wright #:nodoc:
       end
       private_class_method :user_mask
 
-      MODE_MAP = { #:nodoc:
+      MODE_MAP = {
         'r' => 0444,
         'w' => 0222,
         'x' => 0111,
@@ -59,22 +59,20 @@ module Wright #:nodoc:
       end
       private_class_method :mode_mask
 
-      # Internal: Convert a symbolic mode string to an integer mode
-      # value.
-      #
-      # mode - The symbolic mode string.
-      # base_mode - The integer base mode.
-      # filetype - The filetype. Defaults to :file.
+      # Converts a symbolic mode string to an integer mode value.
       #
-      # Examples
+      # @param mode [String] the symbolic mode string
+      # @param base_mode [Integer] the base mode
+      # @param filetype [Symbol] the filetype
       #
+      # @example
       #   Wright::Util::File.symbolic_mode_to_i('u=rw,go=r', 0400).to_s(8)
       #   # => "644"
       #
       #   Wright::Util::File.symbolic_mode_to_i('u=rw,g+r', 0200).to_s(8)
       #   # => "640"
       #
-      # Returns the integer mode.
+      # @return [Integer] the integer mode
       def self.symbolic_mode_to_i(mode, base_mode, filetype = :file)
         is_directory = (filetype == :directory)
         unless symbolic_mode?(mode)
@@ -87,23 +85,22 @@ module Wright #:nodoc:
         mode_i
       end
 
-      # Internal: Convert a single symbolic mode clause to an integer
-      # mode value.
-      #
-      # mode_clause - The symbolic mode clause.
-      # base_mode_i - The integer base mode.
-      # is_directory - Denotes whether the mode_clause should be
-      #                treated as a symbolic directory mode clause.
+      # Converts a single symbolic mode clause to an integer mode
+      # value.
       #
-      # Examples
+      # @param mode_clause [String] the symbolic mode clause
+      # @param base_mode_i [Integer] the integer base mode
+      # @param is_directory [Bool] denotes whether the mode_clause
+      #   should be treated as a symbolic directory mode clause
       #
+      # @example
       #   Wright::Util::File.mode_clause_to_i('g+r', 0600, false).to_s(8)
       #   # => "640"
       #
       #   Wright::Util::File.mode_clause_to_i('+rw', 0600, false).to_s(8)
       #   # => "666"
       #
-      # Returns the mode clause as an integer.
+      # @return [Integer] the mode clause as an integer
       def self.mode_clause_to_i(mode_clause, base_mode_i, is_directory)
         mode_clause = "a#{mode_clause}" if mode_clause =~ /\A[+-=]/
         who, op, perm = mode_clause.split(/([+-=])/)
@@ -126,12 +123,11 @@ module Wright #:nodoc:
       end
       private_class_method :apply_user_mode_masks
 
-      # Internal: Convert a numeric mode string to an integer mode.
-      #
-      # mode - The numeric mode string.
+      # Converts a numeric mode string to an integer mode.
       #
-      # Examples
+      # @param mode [String, #to_i] the numeric mode string
       #
+      # @example
       #   Wright::Util::File.numeric_mode_to_i('0600').to_s(8)
       #   # => "600"
       #
@@ -144,8 +140,8 @@ module Wright #:nodoc:
       #   Wright::Util::File.numeric_mode_to_i('invalid_mode').to_s(8)
       #   # => nil
       #
-      # Returns the mode in integer form or nil if the mode could not
-      # be converted.
+      # @return [Integer] the mode in integer form or +nil+ if the
+      #   mode could not be converted
       def self.numeric_mode_to_i(mode)
         return mode.to_i unless mode.is_a?(String)
         mode =~ /\A[0-7]{3,4}\Z/ ? mode.to_i(8) : nil
@@ -159,29 +155,27 @@ module Wright #:nodoc:
       end
       private_class_method :symbolic_mode?
 
-      # Internal: Get a file's current mode.
+      # Returns a file's current mode.
       #
-      # path - The file's path.
-      #
-      # Examples
+      # @param path [String] the file's path
       #
+      # @example
       #   FileUtils.touch('foo')
       #   FileUtils.chmod(0644, 'foo')
       #   Wright::Util::File.file_mode('foo').to_s(8)
       #   # => "644"
       #
-      # Returns the file mode as an integer or nil if the file does
-      # not exist.
+      # @return [Integer] the file mode as an integer or +nil+ if the
+      #   file does not exist
       def self.file_mode(path)
         ::File.exist?(path) ? (::File.stat(path).mode & 07777) : nil
       end
 
-      # Internal: Get a file's owner.
-      #
-      # path - The file's path.
+      # Returns a file's owner.
       #
-      # Examples
+      # @param path [String] the file's path
       #
+      # @example
       #   FileUtils.touch('foo')
       #   FileUtils.chown(0, 0, 'foo')
       #   Wright::Util::File.file_owner('foo')
@@ -190,18 +184,17 @@ module Wright #:nodoc:
       #   Wright::Util::File.file_owner('nonexistent')
       #   # => nil
       #
-      # Returns the file owner's uid or nil if the file does not
-      # exist.
+      # @return [Integer] the file owner's uid or +nil+ if the file
+      #   does not exist
       def self.file_owner(path)
         ::File.exist?(path) ? ::File.stat(path).uid : nil
       end
 
-      # Internal: Get a file's owner.
-      #
-      # path - The file's path.
+      # Returns a file's owner.
       #
-      # Examples
+      # @param path [String] the file's path
       #
+      # @example
       #   FileUtils.touch('foo')
       #   FileUtils.chown(0, 0, 'foo')
       #   Wright::Util::File.file_group('foo')
@@ -210,19 +203,18 @@ module Wright #:nodoc:
       #   Wright::Util::File.file_group('nonexistent')
       #   # => nil
       #
-      # Returns the file owner's uid or nil if the file does not
-      # exist.
+      # @return [Integer] the file owner's uid or nil if the file does
+      #   not exist.
       def self.file_group(path)
         ::File.exist?(path) ? ::File.stat(path).gid : nil
       end
 
-      # Internal: Expand tilde symbols in file paths. Path elements
-      # other than the first one are left alone.
+      # Expands tilde symbols in file paths. Path elements other than
+      # the first one are left alone.
       #
-      # path - The file path.
-      #
-      # Examples
+      # @param path [String] the file path
       #
+      # @example
       #   Wright::Util::File.expand_tilde_path('~root/foo')
       #   # => "/root/foo"
       #
@@ -232,7 +224,7 @@ module Wright #:nodoc:
       #   Wright::Util::File.expand_tilde_path('../foo/bar')
       #   # => "../foo/bar"
       #
-      # Returns the expanded String path.
+      # @return [String] the expanded path
       def self.expand_tilde_path(path)
         return path unless path.start_with?('~')
 
@@ -240,13 +232,16 @@ module Wright #:nodoc:
         ::File.join(::File.expand_path(first), rest)
       end
 
-      # Internal: Creates a link named link_name to target.
+      # Creates symlinks without descending into directories.
       #
       # If the file denoted by link_name is a symlink to a directory,
-      # ln_sfn does not descend into it. Behaves similar to GNU ln(1) or
-      # OpenBSD ln(1) when using "ln -sfn to link_name".
+      # {ln_sfn} does not descend into it. Behaves similar to GNU
+      # ln(1) or OpenBSD ln(1) when using +ln -sfn target link_name+.
+      #
+      # @param target [String] the link target
+      # @param link_name [String] the link name
       #
-      # Returns nothing.
+      # @return [void]
       def self.ln_sfn(target, link_name)
         if ::File.symlink?(link_name) && ::File.directory?(link_name)
           FileUtils.rm(link_name)

data/lib/wright/util/file_permissions.rb

@@ -3,14 +3,17 @@ require 'wright/util/user'
 
 module Wright
   module Util
-    # Internal: Helper class to manage file permissions.
+    # Helper class to manage file permissions.
     class FilePermissions
-      # Internal: Create a FilePermissions from a Wright::Resource.
+      # Creates a FilePermissions object from a
+      # {Wright::Resource::File} or {Wright::Resource::Directory}.
       #
-      # resource - The resource object.
-      # filetype - The file's type, typically :file or :directory.
+      # @param resource [Wright::Resource::File,
+      #   Wright::Resource::Directory] the resource object
+      # @param filetype [Symbol] the file's type (+:file+ or +:directory+)
       #
-      # Returns a Wright::Util::FilePermissions object.
+      # @return [Wright::Util::FilePermissions] the FilePermissions
+      #   object
       def self.create_from_resource(resource, filetype)
         filepath = ::File.expand_path(resource.name)
         p = Wright::Util::FilePermissions.new(filepath, filetype)
@@ -20,25 +23,25 @@ module Wright
         p
       end
 
-      # Internal: Get/Set the target file's name.
+      # @return [String] the target file's name
       attr_accessor :filename
 
-      # Internal: Get/Set the file's target group.
-      attr_accessor :group
+      # @return [Integer] the file's target group id
+      attr_reader :group
 
-      # Internal: Get/Set the file's target mode.
-      attr_accessor :mode
+      # @return [Integer] the file's target mode
+      attr_reader :mode
 
-      # Internal: Get the file's target owner.
+      # @return [Integer] the file's target owner uid
       attr_reader :owner
 
-      # Internal: Supported filetypes.
       VALID_FILETYPES = [:file, :directory]
+      private_constant :VALID_FILETYPES
 
-      # Internal: Initialize a FilePermissions object.
+      # Initializes a FilePermissions object.
       #
-      # filename - The file's name.
-      # filetype - The file's type, typically :file or :directory.
+      # @param filename [String] the file's name
+      # @param filetype [Symbol] the file's type (+:file+ or +:directory+)
       def initialize(filename, filetype)
         unless VALID_FILETYPES.include?(filetype)
           fail ArgumentError, "Invalid filetype '#{filetype}'"
@@ -47,17 +50,17 @@ module Wright
         @filetype = filetype
       end
 
-      # Internal: Set the file's owner.
+      # Sets the file's owner
       def owner=(owner)
         @owner = Util::User.user_to_uid(owner)
       end
 
-      # Internal: Set the file's group
+      # Sets the file's group
       def group=(group)
         @group = Util::User.group_to_gid(group)
       end
 
-      # Internal: Set the file's mode.
+      # Sets the file's mode
       def mode=(mode)
         if mode.nil?
           @mode = nil
@@ -72,7 +75,9 @@ module Wright
         @mode = mode_i
       end
 
-      # Internal: Check if the file's owner, group and mode are up-to-date.
+      # Checks if the file's owner, group and mode are up-to-date
+      # @return [Bool] +true+ if the file is up to date, +false+
+      #   otherwise
       def uptodate?
         if ::File.exist?(@filename)
           owner_uptodate? && group_uptodate? && mode_uptodate?
@@ -81,23 +86,25 @@ module Wright
         end
       end
 
-      # Internal: Update the file's owner, group and mode.
+      # Updates the file's owner, group and mode.
+      #
+      # @return [void]
       def update
         ::File.chmod(@mode, @filename) if @mode
         ::File.chown(@owner, @group, @filename) if @owner || @group
       end
 
-      # Internal: Get the file's current mode.
+      # @return [Integer] the file's current mode
       def current_mode
         Wright::Util::File.file_mode(@filename)
       end
 
-      # Internal: Get the file's current owner.
+      # @return [Integer] the file's current owner's uid
       def current_owner
         Wright::Util::File.file_owner(@filename)
       end
 
-      # Internal: Get the file's current group.
+      # @return [Integer] the file's current group's gid
       def current_group
         Wright::Util::File.file_group(@filename)
       end

data/lib/wright/util/recursive_autoloader.rb

@@ -2,22 +2,20 @@ require 'wright/util'
 
 module Wright
   module Util
-    # Internal: Recursive autoloader, recursively adds autoloads for
-    # all files in a directory.
+    # Recursive autoloader, recursively adds autoloads for all files
+    # in a directory.
     module RecursiveAutoloader
-      # Internal: Adds autoloads for all files in a directory to a
-      # parent class.
+      # Adds autoloads for all files in a directory to a parent class.
       #
       # Registers all files in directory to be autoloaded the
       # first time ParentClass::CamelCased::FileName is accessed.
       #
-      # directory - The path of the directory containing the files to
-      #             be autoloaded.
-      #
-      # parent_class - The parent class to add the autoloads to.
-      #
-      # Examples
+      # @param directory [String] the path of the directory containing
+      #   the files to be autoloaded
+      # @param parent_class [String] the parent class to add the
+      #   autoloads to
       #
+      # @example
       #   require 'fileutils'
       #
       #   # set up a test directory
@@ -42,8 +40,8 @@ module Wright
       #   Root::Foo.autoload? 'BarBaz'
       #   # => nil
       #
-      # Returns nothing.
-      # Raises ArgumentError if the parent class cannot be resolved.
+      # @return [void]
+      # @raise [ArgumentError] if the parent class cannot be resolved
       def self.add_autoloads(directory, parent_class)
         unless class_exists?(parent_class)
           fail ArgumentError, "Can't resolve parent_class #{parent_class}"