wright 0.1.1 → 0.1.2

data/lib/wright/provider/symlink.rb

@@ -3,11 +3,11 @@ require 'fileutils'
 
 module Wright
   class Provider
-    # Public: Symlink provider. Used as a Provider for Resource::Symlink.
+    # Symlink provider. Used as a provider for {Resource::Symlink}.
     class Symlink < Wright::Provider
-      # Public: Create or update the Symlink.
+      # Creates or updates the symlink.
       #
-      # Returns nothing.
+      # @return [void]
       def create
         if exist?
           symlink = symlink_to_s(@resource.name, @resource.to)
@@ -20,9 +20,9 @@ module Wright
         @updated = true
       end
 
-      # Public: Remove the Symlink.
+      # Removes the symlink.
       #
-      # Returns nothing.
+      # @return [void]
       def remove
         if ::File.exist?(link_name) && !::File.symlink?(link_name)
           fail "'#{link_name}' is not a symlink"
@@ -38,11 +38,11 @@ module Wright
 
       private
 
-      # Internal: Checks if the specified link exists.
+      # Checks if the specified link exists.
       #
-      # Returns true if the link exists and points to the specified target
-      # and false otherwise.
-      def exist? #:doc:
+      # Returns true if the link exists and points to the specified
+      # target and false otherwise.
+      def exist?
         ::File.symlink?(link_name) &&
           ::File.readlink(link_name) == link_to
       end

data/lib/wright/resource.rb

@@ -4,11 +4,11 @@ require 'wright/logger'
 require 'wright/dry_run'
 
 module Wright
-  # Public: Resource base class.
+  # Resource base class.
   class Resource
-    # Public: Initialize a Resource.
+    # Initializes a Resource.
     #
-    # name - The resource's name.
+    # @param name [String] the name of the resource
     def initialize(name = nil)
       @name = name
       @resource_name = Util.class_to_resource_name(self.class).to_sym
@@ -18,16 +18,15 @@ module Wright
       @ignore_failure = false
     end
 
-    # Public: Get/Set the name Symbol of the method to be run by run_action.
+    # @return [Symbol] the name of the method to be run by {#run_action}
     attr_accessor :action
 
-    # Public: Get/Set the ignore_failure attribute.
+    # @return [Bool] the ignore_failure attribute
     attr_accessor :ignore_failure
 
-    # Public: Get/Set the resource's name attribute.
-    #
-    # Examples
+    # @return [String] the resource's name attribute
     #
+    # @example
     #   foo = Wright::Resource::Symlink.new('/tmp/fstab')
     #   foo.name
     #   # => "/tmp/fstab"
@@ -38,22 +37,21 @@ module Wright
     #   # => "/tmp/passwd"
     attr_accessor :name
 
-    # Public: Returns a compact resource name Symbol.
-    #
-    # Examples
+    # @return [Symbol] a compact resource name
     #
+    # @example
     #   foo = Wright::Resource::Symlink.new
     #   foo.resource_name
     #   # => :symlink
     attr_reader :resource_name
 
-    # Public: Set an update action for a resource.
+    # Sets an update action for a resource.
     #
-    # on_update - The block that is called if the resource is
-    #             updated. Has to respond to :call.
+    # @param on_update [Proc, #call] the block that is called when the
+    #   resource is updated.
     #
-    # Returns nothing.
-    # Raises ArgumentError if on_update is not callable
+    # @return [void]
+    # @raise [ArgumentError] if on_update is not callable
     def on_update=(on_update)
       if on_update.respond_to?(:call) || on_update.nil?
         @on_update = on_update
@@ -62,28 +60,29 @@ module Wright
       end
     end
 
-    # Public: Run the resource's current action.
-    #
-    # Examples
+    # Runs the resource's current action.
     #
+    # @example
     #   fstab = Wright::Resource::Symlink.new('/tmp/fstab')
     #   fstab.action = :remove
     #   fstab.run_action
+    #
+    # @return the return value of the current action
     def run_action
       send @action if @action
     end
 
     private
 
-    # Public: Mark a code block that might update a resource.
+    # @api public
+    # Marks a code block that might update a resource.
     #
     # Usually this method is called in the definition of a new
     # resource class in order to mark those methods that should be
     # able to trigger update actions. Runs the current update action
     # if the provider was updated by the block method.
     #
-    # Examples
-    #
+    # @example
     #   class BalloonAnimal < Wright::Provider
     #     def inflate
     #       puts "It's a giraffe!"
@@ -101,8 +100,9 @@ module Wright
     #   balloon = Balloon.new.inflate
     #   # => true
     #
-    # Returns true if the provider was updated and false otherwise.
-    def might_update_resource #:doc:
+    # @return [Bool] true if the provider was updated and false
+    #   otherwise
+    def might_update_resource
       begin
         yield
       rescue => e

data/lib/wright/resource/directory.rb

@@ -3,16 +3,15 @@ require 'wright/dsl'
 
 module Wright
   class Resource
-    # Public: Directory resource, represents a directory.
-    #
-    # Examples
+    # Directory resource, represents a directory.
     #
+    # @example
     #   dir = Wright::Resource::Directory.new('/tmp/foobar')
     #   dir.create
     class Directory < Wright::Resource
-      # Public: Initialize a Directory.
+      # Initializes a Directory.
       #
-      # name - The directory's name.
+      # @param name [String] the directory's name
       def initialize(name)
         super
         @mode = nil
@@ -21,13 +20,13 @@ module Wright
         @action = :create
       end
 
-      # Public: Get/Set the directory's mode.
+      # @return [String, Integer] the directory's mode
       attr_accessor :mode
 
-      # Public: Get the directory's owner.
+      # @return [String] the directory's owner
       attr_reader :owner
 
-      # Public: Set the directory's owner.
+      # Sets the directory's owner.
       def owner=(owner)
         target_owner, target_group =
           Wright::Util::User.owner_to_owner_group(owner)
@@ -35,26 +34,28 @@ module Wright
         @group = target_group unless target_group.nil?
       end
 
-      # Public: Get the directory's group.
+      # @return [String] the directory's group
       attr_reader :group
 
-      # Public: Set the directory's group
+      # Sets the directory's group.
       def group=(group)
         @group = Wright::Util::User.group_to_gid(group)
       end
 
-      # Public: Create or update the directory.
+      # Creates or updates the directory.
       #
-      # Returns true if the directory was updated and false otherwise.
+      # @return [Bool] true if the directory was updated and false
+      #   otherwise
       def create
         might_update_resource do
           @provider.create
         end
       end
 
-      # Public: Remove the directory.
+      # Removes the directory.
       #
-      # Returns true if the directory was updated and false otherwise.
+      # @return [Bool] true if the directory was updated and false
+      #   otherwise
       def remove
         might_update_resource do
           @provider.remove

data/lib/wright/resource/file.rb

@@ -3,29 +3,28 @@ require 'wright/dsl'
 
 module Wright
   class Resource
-    # Public: Symlink resource, represents a symlink.
-    #
-    # Examples
+    # Symlink resource, represents a symlink.
     #
+    # @example
     #   file = Wright::Resource::File.new('/tmp/foo')
     #   file.content = 'bar'
     #   file.create
     class File < Wright::Resource
-      # Public: Get/Set the file's content.
+      # @return [String] the file's intended content
       attr_accessor :content
 
-      # Public: Get/Set the file's group.
+      # @return [String] the file's intended group.
       attr_accessor :group
 
-      # Public: Get/Set the file's mode.
+      # @return [String, Integer] the file's intended mode
       attr_accessor :mode
 
-      # Public: Get the file's owner.
+      # @return [String] the file's intended owner
       attr_reader :owner
 
-      # Public: Initialize a File.
+      # Initializes a File.
       #
-      # name - The file's name.
+      # @param name [String] the file's name
       def initialize(name)
         super
         @content = nil
@@ -35,7 +34,7 @@ module Wright
         @action = :create
       end
 
-      # Public: Set the file's owner.
+      # Sets the file's owner.
       def owner=(owner)
         target_owner, target_group =
           Wright::Util::User.owner_to_owner_group(owner)
@@ -43,18 +42,20 @@ module Wright
         @group = target_group unless target_group.nil?
       end
 
-      # Public: Create or update the File.
+      # Creates or updates the file.
       #
-      # Returns true if the file was updated and false otherwise.
+      # @return [Bool] true if the file was updated and false
+      #   otherwise
       def create
         might_update_resource do
           @provider.create
         end
       end
 
-      # Public: Remove the File.
+      # Removes the file.
       #
-      # Returns true if the file was updated and false otherwise.
+      # @return [Bool] true if the file was updated and false
+      #   otherwise
       def remove
         might_update_resource do
           @provider.remove

data/lib/wright/resource/package.rb

@@ -3,10 +3,9 @@ require 'wright/dsl'
 
 module Wright
   class Resource
-    # Public: Package resource, represents a package.
-    #
-    # Examples
+    # Package resource, represents a package.
     #
+    # @example
     #   vim = Wright::Resource::Package.new('vim')
     #   vim.installed_versions
     #   # => []
@@ -21,42 +20,44 @@ module Wright
     #   htop.installed_versions
     #   # => []
     class Package < Wright::Resource
-      # Public: Get/Set the package version to install/remove.
+      # @return [String] the package version to install or remove
       attr_accessor :version
 
-      # Public: Initialize a Package.
+      # Initializes a Package.
       #
-      # name - The package name.
+      # @param name [String] the package's name
       def initialize(name)
         super
         @version = nil
         @action = :install
       end
 
-      # Public: Get the installed version of a package.
-      #
-      # Returns an array of installed package version Strings.
+      # @return [Array<String>] the installed package versions
       def installed_versions
         @provider.installed_versions
       end
 
-      # Public: Install the Package.
+      # Installs the Package.
       #
-      # Returns true if the package was updated and false otherwise.
+      # @return [Bool] true if the package was updated and false
+      #   otherwise
       def install
         might_update_resource do
           @provider.install
         end
       end
 
-      # Public: Remove the Package.
+      # Removes the Package.
       #
-      # Returns true if the package was updated and false otherwise.
+      # @return [Bool] true if the package was updated and false
+      #   otherwise
       def remove
         might_update_resource do
           @provider.remove
         end
       end
+
+      alias_method :uninstall, :remove
     end
   end
 end

data/lib/wright/resource/symlink.rb

@@ -3,38 +3,39 @@ require 'wright/dsl'
 
 module Wright
   class Resource
-    # Public: Symlink resource, represents a symlink.
-    #
-    # Examples
+    # Symlink resource, represents a symlink.
     #
+    # @example
     #   link = Wright::Resource::Symlink.new('/tmp/fstab')
     #   link.to = '/etc/fstab'
     #   link.create
     class Symlink < Wright::Resource
-      # Public: Initialize a Symlink.
+      # Initializes a Symlink.
       #
-      # name - The link's name.
+      # @param name [String] the symlink's name
       def initialize(name)
         super
         @to = nil
         @action = :create
       end
 
-      # Public: Get/Set the link's target.
+      # @return [String] the symlink's intended target
       attr_accessor :to
 
-      # Public: Create or update the Symlink.
+      # Creates or updates the symlink.
       #
-      # Returns true if the symlink was updated and false otherwise.
+      # @return [Bool] true if the symlink was updated and false
+      #   otherwise
       def create
         might_update_resource do
           @provider.create
         end
       end
 
-      # Public: Remove the Symlink.
+      # Removes the symlink.
       #
-      # Returns true if the symlink was updated and false otherwise.
+      # @return [Bool] true if the symlink was updated and false
+      #   otherwise
       def remove
         might_update_resource do
           @provider.remove

data/lib/wright/util.rb

@@ -1,38 +1,37 @@
 require 'wright/util/stolen_from_activesupport'
 
 module Wright
-  # Internal: Various utility functions.
+  # @api private
+  # Various utility functions.
   module Util
-    # Internal: Get the resource name corresponding to a class.
+    # Converts a class constant into its corresponding resource name.
     #
-    # klass - The class constant for which to get the resource name.
-    #
-    # Examples
+    # @param klass [Class] the class constant
     #
+    # @example
     #   Wright::Util.class_to_resource_name(Wright::Resource::Package)
     #   # => "package"
     #
     #   Wright::Util.class_to_resource_name(Foo::Bar::BazQux)
     #   # => "baz_qux"
     #
-    # Returns the String resource name of the given class.
+    # @return [String] the resource name of the given class
     def self.class_to_resource_name(klass)
       ActiveSupport.underscore(klass.name).split('/').last
     end
 
-    # Internal: Get the class name corresponding to a file path.
-    #
-    # filename - The filename for which to get the class name.
+    # Converts a file path into its corresponding class name.
     #
-    # Examples
+    # @param filename [String] the filename
     #
-    #   Wright::Util.filename_to_classname("foo/bar/baz.rb")
+    # @example
+    #   Wright::Util.filename_to_classname('foo/bar/baz.rb')
     #   # => "Foo::Bar::Baz"
     #
-    #   Wright::Util.filename_to_classname("foo/bar/")
+    #   Wright::Util.filename_to_classname('foo/bar/')
     #   # => "Foo::Bar"
     #
-    # Returns the String class name for the given filename.
+    # @return [String] the class name for the given filename
     def self.filename_to_classname(filename)
       ActiveSupport.camelize(filename.chomp('.rb').chomp('/'))
     end
@@ -45,18 +44,17 @@ module Wright
     end
     private_class_method :distro
 
-    # Internal: Get the system's OS family.
-    #
-    # Examples
+    # Determines the system's OS family.
     #
+    # @example
     #   Wright::Util.os_family
     #   # => "debian"
-    #
+    # @example
     #   Wright::Util.os_family
     #   # => "macosx"
     #
-    # Returns the String system OS family (base distribution for
-    # GNU/Linux systems) or 'other' for unknown operating systems.
+    # @return [String] the system's OS family (base distribution for
+    #   GNU/Linux systems) or 'other' for unknown operating systems
     def self.os_family
       system_arch = RbConfig::CONFIG['target_os']
       case system_arch