Updated documentation. Also changed the defaults of :path and :url to something…

Updated documentation. Also changed the defaults of :path and :url to something more sane and defaultable.

Rakefile

@@ -27,7 +27,7 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'doc'
   rdoc.title    = 'Paperclip'
   rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
@@ -70,10 +70,6 @@ spec = Gem::Specification.new do |s|
   s.add_development_dependency 'mocha'
 end
  
-Rake::GemPackageTask.new(spec) do |pkg| 
-  pkg.need_tar = true 
-end 
-
 desc "Release new version"
 task :release => [:test, :sync_docs, :gem] do
   require 'rubygems'

lib/paperclip.rb

@@ -63,13 +63,15 @@ module Paperclip
 
     def path_for_command command #:nodoc:
       if options[:image_magick_path]
-        ActiveSupport::Deprecation.warn(":image_magick_path is deprecated and will be removed. Use :command_path instead")
+        ActiveSupport::Deprecation.warn(":image_magick_path is deprecated and "+
+                                        "will be removed. Use :command_path "+
+                                        "instead")
       end
       path = [options[:image_magick_path] || options[:command_path], command].compact
       File.join(*path)
     end
 
-    def run cmd, params = "", expected_outcodes = 0
+    def run cmd, params = "", expected_outcodes = 0 #:nodoc:
       output = `#{%Q[#{path_for_command(cmd)} #{params} 2>#{bit_bucket}].gsub(/\s+/, " ")}`
       unless [expected_outcodes].flatten.include?($?.exitstatus)
         raise PaperclipCommandLineError, "Error while running #{cmd}"
@@ -77,19 +79,23 @@ module Paperclip
       output
     end
 
-    def bit_bucket
+    def bit_bucket #:nodoc:
       File.exists?("/dev/null") ? "/dev/null" : "NUL"
     end
 
     def included base #:nodoc:
       base.extend ClassMethods
-      base.send(:include, Paperclip::CallbackCompatability) unless base.respond_to?(:define_callbacks)
+      unless base.respond_to?(:define_callbacks)
+        base.send(:include, Paperclip::CallbackCompatability)
+      end
     end
 
-    def processor name
+    def processor name #:nodoc:
       name = name.to_s.camelize
       processor = Paperclip.const_get(name)
-      raise PaperclipError.new("Processor #{name} was not found") unless processor.ancestors.include?(Paperclip::Processor)
+      unless processor.ancestors.include?(Paperclip::Processor)
+        raise PaperclipError.new("Processor #{name} was not found") 
+      end
       processor
     end
   end
@@ -116,15 +122,15 @@ module Paperclip
     # * +url+: The full URL of where the attachment is publically accessible. This can just
     #   as easily point to a directory served directly through Apache as it can to an action
     #   that can control permissions. You can specify the full domain and path, but usually
-    #   just an absolute path is sufficient. The leading slash must be included manually for 
+    #   just an absolute path is sufficient. The leading slash *must* be included manually for 
     #   absolute paths. The default value is 
-    #   "/:class/:attachment/:id/:style_:basename.:extension". See
+    #   "/system/:attachment/:id/:style/:basename.:extension". See
     #   Paperclip::Attachment#interpolate for more information on variable interpolaton.
-    #     :url => "/:attachment/:id/:style_:basename:extension"
+    #     :url => "/:class/:attachment/:id/:style_:basename.:extension"
     #     :url => "http://some.other.host/stuff/:class/:id_:extension"
     # * +default_url+: The URL that will be returned if there is no attachment assigned. 
     #   This field is interpolated just as the url is. The default value is 
-    #   "/:class/:attachment/missing_:style.png"
+    #   "/:attachment/:style/missing.png"
     #     has_attached_file :avatar, :default_url => "/images/default_:style_avatar.png"
     #     User.new.avatar_url(:small) # => "/images/default_small_avatar.png"
     # * +styles+: A hash of thumbnail styles and their geometries. You can find more about 
@@ -222,14 +228,16 @@ module Paperclip
       end
     end
     
-    # Places ActiveRecord-style validations on the content type of the file assigned. The
-    # possible options are:
-    # * +content_type+: Allowed content types.  Can be a single content type or an array.
-    #   Each type can be a String or a Regexp. It should be noted that Internet Explorer uploads
-    #   files with content_types that you may not expect. For example, JPEG images are given
-    #   image/pjpeg and PNGs are image/x-png, so keep that in mind when determining how you match.
-    #   Allows all by default.
-    # * +message+: The message to display when the uploaded file has an invalid content type.
+    # Places ActiveRecord-style validations on the content type of the file
+    # assigned. The possible options are: 
+    # * +content_type+: Allowed content types.  Can be a single content type 
+    #   or an array.  Each type can be a String or a Regexp. It should be 
+    #   noted that Internet Explorer upload files with content_types that you 
+    #   may not expect. For example, JPEG images are given image/pjpeg and 
+    #   PNGs are image/x-png, so keep that in mind when determining how you 
+    #   match.  Allows all by default.
+    # * +message+: The message to display when the uploaded file has an invalid
+    #   content type.
     def validates_attachment_content_type name, options = {}
       attachment_definitions[name][:validations][:content_type] = lambda do |attachment, instance|
         valid_types = [options[:content_type]].flatten
@@ -245,11 +253,11 @@ module Paperclip
       end
     end
 
-    # Returns the attachment definitions defined by each call to has_attached_file.
+    # Returns the attachment definitions defined by each call to
+    # has_attached_file.
     def attachment_definitions
       read_inheritable_attribute(:attachment_definitions)
     end
-
   end
 
   module InstanceMethods #:nodoc:

lib/paperclip/attachment.rb

 module Paperclip
-  # The Attachment class manages the files for a given attachment. It saves when the model saves,
-  # deletes when the model is destroyed, and processes the file upon assignment.
+  # The Attachment class manages the files for a given attachment. It saves
+  # when the model saves, deletes when the model is destroyed, and processes
+  # the file upon assignment.
   class Attachment
     
     def self.default_options
       @default_options ||= {
-        :url           => "/:attachment/:id/:style/:basename.:extension",
-        :path          => ":rails_root/public/:attachment/:id/:style/:basename.:extension",
+        :url           => "/system/:attachment/:id/:style/:basename.:extension",
+        :path          => ":rails_root/public/system/:attachment/:id/:style/:basename.:extension",
         :styles        => {},
         :default_url   => "/:attachment/:style/missing.png",
         :default_style => :original,
@@ -17,9 +18,9 @@ module Paperclip
 
     attr_reader :name, :instance, :styles, :default_style, :convert_options, :queued_for_write
 
-    # Creates an Attachment object. +name+ is the name of the attachment, +instance+ is the
-    # ActiveRecord object instance it's attached to, and +options+ is the same as the hash
-    # passed to +has_attached_file+.
+    # Creates an Attachment object. +name+ is the name of the attachment,
+    # +instance+ is the ActiveRecord object instance it's attached to, and
+    # +options+ is the same as the hash passed to +has_attached_file+.
     def initialize name, instance, options = {}
       @name              = name
       @instance          = instance
@@ -46,14 +47,17 @@ module Paperclip
       normalize_style_definition
       initialize_storage
 
-      logger.info("[paperclip] Paperclip attachment #{name} on #{instance.class} initialized.")
+      log("Paperclip attachment #{name} on #{instance.class} initialized.")
     end
 
-    # What gets called when you call instance.attachment = File. It clears errors,
-    # assigns attributes, processes the file, and runs validations. It also queues up
-    # the previous file for deletion, to be flushed away on #save of its host.
-    # In addition to form uploads, you can also assign another Paperclip attachment:
+    # What gets called when you call instance.attachment = File. It clears
+    # errors, assigns attributes, processes the file, and runs validations. It
+    # also queues up the previous file for deletion, to be flushed away on
+    # #save of its host.  In addition to form uploads, you can also assign
+    # another Paperclip attachment: 
     #   new_user.avatar = old_user.avatar
+    # If the file that is assigned is not valid, the processing (i.e.
+    # thumbnailing, etc) will NOT be run.
     def assign uploaded_file
       %w(file_name).each do |field|
         unless @instance.class.column_names.include?("#{name}_#{field}")
@@ -66,7 +70,7 @@ module Paperclip
       end
 
       return nil unless valid_assignment?(uploaded_file)
-      logger.info("[paperclip] Assigning #{uploaded_file.inspect} to #{name}")
+      log("Assigning #{uploaded_file.inspect} to #{name}")
 
       uploaded_file.binmode if uploaded_file.respond_to? :binmode
       queue_existing_for_delete
@@ -75,7 +79,7 @@ module Paperclip
 
       return nil if uploaded_file.nil?
 
-      logger.info("[paperclip] Writing attributes for #{name}")
+      log("Writing attributes for #{name}")
       @queued_for_write[:original]   = uploaded_file.to_tempfile
       instance_write(:file_name,       uploaded_file.original_filename.strip.gsub(/[^\w\d\.\-]+/, '_'))
       instance_write(:content_type,    uploaded_file.content_type.to_s.strip)
@@ -92,21 +96,22 @@ module Paperclip
       validate
     end
 
-    # Returns the public URL of the attachment, with a given style. Note that this
-    # does not necessarily need to point to a file that your web server can access
-    # and can point to an action in your app, if you need fine grained security.
-    # This is not recommended if you don't need the security, however, for
-    # performance reasons.
-    # set include_updated_timestamp to false if you want to stop the attachment update time appended to the url
+    # Returns the public URL of the attachment, with a given style. Note that
+    # this does not necessarily need to point to a file that your web server
+    # can access and can point to an action in your app, if you need fine
+    # grained security.  This is not recommended if you don't need the
+    # security, however, for performance reasons.  set
+    # include_updated_timestamp to false if you want to stop the attachment
+    # update time appended to the url
     def url style = default_style, include_updated_timestamp = true
       url = original_filename.nil? ? interpolate(@default_url, style) : interpolate(@url, style)
       include_updated_timestamp && updated_at ? [url, updated_at].compact.join(url.include?("?") ? "&" : "?") : url
     end
 
     # Returns the path of the attachment as defined by the :path option. If the
-    # file is stored in the filesystem the path refers to the path of the file on
-    # disk. If the file is stored in S3, the path is the "key" part of the URL,
-    # and the :bucket option refers to the S3 bucket.
+    # file is stored in the filesystem the path refers to the path of the file
+    # on disk. If the file is stored in S3, the path is the "key" part of the
+    # URL, and the :bucket option refers to the S3 bucket.
     def path style = nil #:nodoc:
       original_filename.nil? ? nil : interpolate(@path, style)
     end
@@ -136,32 +141,38 @@ module Paperclip
     # the instance's errors and returns false, cancelling the save.
     def save
       if valid?
-        logger.info("[paperclip] Saving files for #{name}")
+        log("Saving files for #{name}")
         flush_deletes
         flush_writes
         @dirty = false
         true
       else
-        logger.info("[paperclip] Errors on #{name}. Not saving.")
+        log("Errors on #{name}. Not saving.")
         flush_errors
         false
       end
     end
 
-    # Returns the name of the file as originally assigned, and as lives in the
+    # Returns the name of the file as originally assigned, and lives in the
     # <attachment>_file_name attribute of the model.
     def original_filename
       instance_read(:file_name)
     end
 
+    # Returns the size of the file as originally assigned, and lives in the
+    # <attachment>_file_size attribute of the model.
     def size
       instance_read(:file_size) || (@queued_for_write[:original] && @queued_for_write[:original].size)
     end
 
+    # Returns the content_type of the file as originally assigned, and lives
+    # in the <attachment>_content_type attribute of the model.
     def content_type
       instance_read(:content_type)
     end
     
+    # Returns the last modified time of the file as originally assigned, and 
+    # lives in the <attachment>_updated_at attribute of the model.
     def updated_at
       time = instance_read(:updated_at)
       time && time.to_i
@@ -195,10 +206,10 @@ module Paperclip
       }
     end
 
-    # This method really shouldn't be called that often. It's expected use is in the
-    # paperclip:refresh rake task and that's it. It will regenerate all thumbnails
-    # forcefully, by reobtaining the original file and going through the post-process
-    # again.
+    # This method really shouldn't be called that often. It's expected use is
+    # in the paperclip:refresh rake task and that's it. It will regenerate all
+    # thumbnails forcefully, by reobtaining the original file and going through
+    # the post-process again.
     def reprocess!
       new_original = Tempfile.new("paperclip-reprocess")
       if old_original = to_file(:original)
@@ -216,16 +227,22 @@ module Paperclip
       end
     end
     
+    # Returns true if a file has been assigned.
     def file?
       !original_filename.blank?
     end
 
+    # Writes the attachment-specific attribute on the instance. For example,
+    # instance_write(:file_name, "me.jpg") will write "me.jpg" to the instance's
+    # "avatar_file_name" field (assuming the attachment is called avatar).
     def instance_write(attr, value)
       setter = :"#{name}_#{attr}="
       responds = instance.respond_to?(setter)
       instance.send(setter, value) if responds || attr.to_s == "file_name"
     end
 
+    # Reads the attachment-specific attribute on the instance. See instance_write
+    # for more details.
     def instance_read(attr)
       getter = :"#{name}_#{attr}"
       responds = instance.respond_to?(getter)
@@ -238,6 +255,10 @@ module Paperclip
       instance.logger
     end
 
+    def log message
+      logger.info("[paperclip] #{message}")
+    end
+
     def valid_assignment? file #:nodoc:
       file.nil? || (file.respond_to?(:original_filename) && file.respond_to?(:content_type))
     end
@@ -290,7 +311,7 @@ module Paperclip
       return if @queued_for_write[:original].nil?
       return if callback(:before_post_process) == false
       return if callback(:"before_#{name}_post_process") == false
-      logger.info("[paperclip] Post-processing #{name}")
+      log("Post-processing #{name}")
       @styles.each do |name, args|
         begin
           @queued_for_write[name] = @queued_for_write[:original]
@@ -321,7 +342,7 @@ module Paperclip
 
     def queue_existing_for_delete #:nodoc:
       return unless file?
-      logger.info("[paperclip] Queueing the existing files for #{name} for deletion.")
+      log("Queueing the existing files for #{name} for deletion.")
       @queued_for_delete += [:original, *@styles.keys].uniq.map do |style|
         path(style) if exists?(style)
       end.compact

lib/paperclip/callback_compatability.rb

 module Paperclip
-  # This module is intended as a compatability shim for the differences in callbacks
-  # between Rails 2.0 and Rails 2.1.
+  # This module is intended as a compatability shim for the differences in
+  # callbacks between Rails 2.0 and Rails 2.1.
   module CallbackCompatability
     def self.included(base)
       base.extend(ClassMethods)

lib/paperclip/iostream.rb

@@ -30,7 +30,7 @@ module IOStream
   end
 end
 
-class IO
+class IO #:nodoc:
   include IOStream
 end
 

shoulda_macros/paperclip.rb

 module Paperclip
+  # =Paperclip Shoulda Macros
+  #
+  # These macros are intended for use with shoulda, and will be included into
+  # your tests automatically. All of the macros use the standard shoulda
+  # assumption that the name of the test is based on the name of the model
+  # you're testing (that is, UserTest is the test for the User model), and
+  # will load that class for testing purposes.
   module Shoulda
+    # This will test whether you have defined your attachment correctly by
+    # checking for all the required fields exist after the definition of the
+    # attachment.
     def should_have_attached_file name, options = {}
       klass = self.name.gsub(/Test$/, '').constantize
       context "Class #{klass.name} with attachment #{name}" do
@@ -11,6 +21,7 @@ module Paperclip
       end
     end
 
+    # Tests for validations on the presence of the attachment.
     def should_validate_attachment_presence name
       klass   = self.name.gsub(/Test$/, '').constantize
       context "Class #{klass.name} validating presence on #{name}" do
@@ -33,9 +44,12 @@ module Paperclip
           end
         end
       end
-
     end
 
+    # Tests that you have content_type validations specified. There are two
+    # options, :valid and :invalid. Both accept an array of strings. The
+    # strings should be a list of content types which will pass and fail
+    # validation, respectively.
     def should_validate_attachment_content_type name, options = {}
       klass   = self.name.gsub(/Test$/, '').constantize
       valid   = [options[:valid]].flatten
@@ -70,9 +84,14 @@ module Paperclip
           end
         end
       end
-
     end
 
+    # Tests to ensure that you have file size validations turned on. You
+    # can pass the same options to this that you can to 
+    # validate_attachment_file_size - :less_than, :greater_than, and :in.
+    # :less_than checks that a file is less than a certain size, :greater_than
+    # checks that a file is more than a certain size, and :in takes a Range or
+    # Array which specifies the lower and upper limits of the file size.
     def should_validate_attachment_size name, options = {}
       klass   = self.name.gsub(/Test$/, '').constantize
       min     = options[:greater_than] || (options[:in] && options[:in].first) || 0

test/attachment_test.rb

@@ -329,7 +329,7 @@ class AttachmentTest < Test::Unit::TestCase
 
       should "return a correct url even if the file does not exist" do
         assert_nil @attachment.to_file
-        assert_match %r{^/avatars/#{@instance.id}/blah/5k\.png}, @attachment.url(:blah)
+        assert_match %r{^/system/avatars/#{@instance.id}/blah/5k\.png}, @attachment.url(:blah)
       end
 
       should "make sure the updated_at mtime is in the url if it is defined" do
@@ -388,8 +388,8 @@ class AttachmentTest < Test::Unit::TestCase
             should "return the real url" do
               file = @attachment.to_file
               assert file
-              assert_match %r{^/avatars/#{@instance.id}/original/5k\.png}, @attachment.url
-              assert_match %r{^/avatars/#{@instance.id}/small/5k\.jpg}, @attachment.url(:small)
+              assert_match %r{^/system/avatars/#{@instance.id}/original/5k\.png}, @attachment.url
+              assert_match %r{^/system/avatars/#{@instance.id}/small/5k\.jpg}, @attachment.url(:small)
               file.close
             end