rdoc updates for sprite classes

lib/compass/sass_extensions/sprites/base.rb

@@ -2,6 +2,10 @@ module Compass
   module SassExtensions
     module Sprites
       class Base < Sass::Script::Literal
+        
+        
+        # Initialize a new aprite object from a relative file path
+        # the path is relative to the <tt>images_path</tt> confguration option
         def self.from_uri(uri, context, kwargs)
           sprite_map = ::Compass::SpriteMap.new(uri.value, {})
 
@@ -10,7 +14,8 @@ module Compass
           end
           new(sprites, sprite_map.path, sprite_map.name, context, kwargs)
         end
-
+        
+        # Loads the sprite engine
         def require_engine!
           self.class.send(:include, eval("::Compass::SassExtensions::Sprites::#{modulize}Engine"))
         end
@@ -41,13 +46,15 @@ module Compass
       
         # Calculates the overal image dimensions
         # collects image sizes and input parameters for each sprite
+        # Calculates the height
         def compute_image_metadata!
           @width = 0
           init_images
           compute_image_positions!
           @height = @images.last.top + @images.last.height
         end
-
+        
+        # Creates the Sprite::Image objects for each image and calculates the width
         def init_images
           @images = image_names.collect do |relative_file|
             image = Compass::SassExtensions::Sprites::Image.new(self, relative_file, options)
@@ -66,27 +73,34 @@ module Compass
             image.top = last_image.top + last_image.height + [image.spacing,  last_image.spacing].max
           end
         end
-
+        
+        # Fetches the Sprite::Image object for the supplied name
         def image_for(name)
           @images.detect { |img| img.name == name}
         end
         
+        # Returns true if the image name has a hover selector image
         def has_hover?(name)
           !image_for("#{name}_hover").nil?
         end
         
+        # Returns true if the image name has a target selector image
         def has_target?(name)
           !image_for("#{name}_target").nil?
         end
         
+        # Returns true if the image name has an active selector image
         def has_active?(name)
           !image_for("#{name}_active").nil?
         end
         
+        # Return and array of image names that make up this sprite
         def sprite_names
           image_names.map { |f| File.basename(f, '.png') }
         end
 
+
+        # Validates that the sprite_names are valid sass
         def validate!
           for sprite_name in sprite_names
             unless sprite_name =~ /\A#{Sass::SCSS::RX::IDENT}\Z/
@@ -108,11 +122,13 @@ module Compass
             Compass.configuration.run_callback(:sprite_generated, sprite_data)
           end
         end
-
+        
+        # Does this sprite need to be generated
         def generation_required?
           !File.exists?(filename) || outdated?
         end
 
+        # Returns the uniqueness hash for this sprite object
         def uniqueness_hash
           @uniqueness_hash ||= begin
             sum = Digest::MD5.new
@@ -128,6 +144,7 @@ module Compass
           @uniqueness_hash
         end
 
+        # Saves the sprite engine
         def save!(output_png)
           saved = output_png.save filename
           Compass.configuration.run_callback(:sprite_saved, filename)
@@ -147,6 +164,7 @@ module Compass
           true
         end
 
+        # Mtime of the sprite file
         def mtime
           File.mtime(filename)
         end

lib/compass/sass_extensions/sprites/engines/chunky_png_engine.rb

@@ -11,7 +11,6 @@ module Compass
         
         # Returns a PNG object
         def construct_sprite
-          #require_png_library!
           output_png = ChunkyPNG::Image.new(width, height, ChunkyPNG::Color::TRANSPARENT)
           images.each do |image|
             input_png  = ChunkyPNG::Image.from_file(image.file)

lib/compass/sass_extensions/sprites/image.rb

@@ -9,23 +9,28 @@ module Compass
           @base, @relative_file, @options = base, relative_file, options
           @left = @top = 0
         end
-
+        
+        # The Full path to the image
         def file
           File.join(Compass.configuration.images_path, relative_file)
         end
-
+        
+        # Width of the image
         def width
           dimensions.first
         end
-
+        
+        # Height of the image
         def height
           dimensions.last
         end
-
+        
+        # Basename of the image
         def name
           File.basename(relative_file, '.png')
         end
 
+        # Value of <tt> $#{name}-repeat </tt> or <tt> $repeat </tt>
         def repeat
           [ "#{name}-repeat", "repeat" ].each { |which|
             if var = options.get_var(which)
@@ -35,46 +40,57 @@ module Compass
           "no-repeat"
         end
 
+        # Value of <tt> $#{name}-position </tt> or <tt> $position </tt> defaults o <tt>0px</tt>
         def position
           options.get_var("#{name}-position") || options.get_var("position") || Sass::Script::Number.new(0, ["px"])
         end
-
+        
+        # Offset within the sprite
         def offset
           (position.unitless? || position.unit_str == "px") ? position.value : 0
         end
-
+        
+        # Spacing between this image and the next
         def spacing
           (options.get_var("#{name}-spacing") || options.get_var("spacing") || Sass::Script::Number.new(0)).value
         end
 
+        # MD5 hash of this file
         def digest
           Digest::MD5.file(file).hexdigest
         end
-
+        
+        # mtime of this file
         def mtime
           File.mtime(file)
         end
         
+        # Has hover selector
         def hover?
           base.has_hover?(name)
         end
         
+        # Hover selector Image object if exsists
         def hover
           base.image_for("#{name}_hover")
         end
         
+        # Has target selector
         def target?
           base.has_target?(name)
         end
         
+        # Target selector Image object if exsists
         def target
           base.image_for("#{name}_target")
         end
         
+        # Has active selector
         def active?
           base.has_active?(name)
         end
         
+        # Active selector Image object if exsists
         def active
           base.image_for("#{name}_active")
         end

lib/compass/sass_extensions/sprites/sprite_map.rb

@@ -6,34 +6,41 @@ module Compass
       @uri, @options = uri, options
     end
 
+    # Name of this spite
     def name
       ensure_path_and_name!
       @name
     end
 
+    # The on-disk location of this sprite
     def path
       ensure_path_and_name!
       @path
     end
-
+    
+    # Returns the Glob of image files for this sprite
     def files
       @files ||= Dir[File.join(Compass.configuration.images_path, uri)].sort
     end
 
+    # Returns an Array of image names without the file extension
     def sprite_names
       @sprite_names ||= files.collect { |file| File.basename(file, '.png') }
     end
 
+    # Returns the sass options for this sprite
     def sass_options
       @sass_options ||= options.merge(:filename => name, :syntax => :scss, :importer => self)
     end
 
+    # Returns the mtime of all image files combined
     def mtime
       Compass.quick_cache("mtime:#{uri}") do
         files.collect { |file| File.mtime(file) }.max
       end
     end
-
+    
+    # Returns a Sass::Engine for this sprite object
     def sass_engine
       Sass::Engine.new(content_for_images, options)
     end
@@ -45,6 +52,7 @@ module Compass
       @path, @name = $1, $3
     end
 
+    # Generates the Sass for this sprite file
     def content_for_images(skip_overrides = false)
       <<-SCSS
 @import "compass/utilities/sprites/base";
@@ -94,7 +102,11 @@ $#{name}-prefix: '' !default;
 }
 SCSS
     end
-
+    
+    # Generates the override defaults for this Sprite
+    # <tt>$#{name}-#{sprite_name}-position </tt>
+    # <tt> $#{name}-#{sprite_name}-spacing </tt>
+    # <tt> #{name}-#{sprite_name}-repeat: </tt>
     def generate_overrides
       content = <<-TXT
 // These variables control the generated sprite output

lib/compass/sass_extensions/sprites/sprites.rb

@@ -1,15 +1,18 @@
 module Compass
   class Sprites < Sass::Importers::Base
+    
     def find_relative(*args)
       nil
     end
-
+    
+    # Called by the sass engine to build a new SpriteMap
     def find(uri, options)
       if uri =~ /\.png$/
         SpriteMap.new(uri, options).sass_engine
       end
     end
-
+    
+    # Called by the sass engine to identift the SpriteMap
     def key(uri, options)
       [self.class.name + ":" + File.dirname(File.expand_path(uri)),
         File.basename(uri)]