Some doc and README.md

README.md

@@ -0,0 +1,51 @@
+
+## Papercrop
+An easy extension for Paperclip to crop your image uploads using jCrop.
+
+### Installation
+Include papercrop in your Gemfile or install it by hand
+
+    gem install papercrop
+
+You need to add the required files in your assets...
+
+In your application.js
+
+    //= require jquery
+    //= require jquery.jcrop
+    //= require papercrop
+
+In your application.css
+
+    *= require jquery.jcrop
+
+### Using Papercrop
+You are a few steps away to start cropping attachments. Let's start with the model, a user with avatar:
+
+    has_attached_file :avatar, :styles => {:thumb => '50x50', :medium => '100x100'}
+    crop_attached_file :avatar
+
+By default, the crop area and the preview box will have an aspect ratio of 1:1. 
+You can modify that by passing a new aspect.
+
+    crop_attached_file :snapshot, :aspect => "16:9"
+
+On the controller you can render a view after user creation, create a simple crop action, etc... whatever you like the most. Inside the form of a persisted user:
+
+    <%= form_for @user do |f| %>
+      <%= f.cropbox :avatar %>
+      <%= f.crop_preview :avatar %>
+      <%= f.submit 'Save' %>
+    <% end %>
+
+Both helpers accept a :width option to customize their dimensions. The preview box has width 100 by default but the cropbox is unlimited in size (takes the original image width), so setting the cropbox width is interesting to avoid layout breaking with huge images. 
+
+    <%= form_for @user do |f| %>
+      <%= f.cropbox :avatar, :width => 500 %>
+      <%= f.crop_preview :avatar, :width => 150 %>
+      <%= f.submit 'Save' %>
+    <% end %>
+
+Regardless of the width passed, the preview box and the cropping area will have the aspect ratio defined in the model (1:1 by default)
+
+That's all!

lib/papercrop/active_record_extension.rb

@@ -8,6 +8,16 @@ def self.included(base)
 
     module ClassMethods
 
+      # Initializes attachment cropping in your model
+      #
+      #   crop_attached_file :avatar
+      #
+      # You can also define an aspect ratio for the crop and preview box through opts[:aspect]
+      #
+      #   crop_attached_file :avatar, :aspect => "4:3"
+      #
+      # @param attachment_name [Symbol] The name of the desired attachment to crop
+      # @param opts [Hash]
       def crop_attached_file(attachment_name, opts = {})
         [:crop_x, :crop_y, :crop_w, :crop_h, :original_w, :original_h, :box_w, :aspect].each do |a|
           attr_accessor :"#{attachment_name}_#{a}"
@@ -36,6 +46,7 @@ def crop_attached_file(attachment_name, opts = {})
 
     module InstanceMethods
 
+      # Asks if the attachment received a crop process
       def cropping?(attachment_name)
         !self.send(:"#{attachment_name}_crop_x").blank? &&
         !self.send(:"#{attachment_name}_crop_y").blank? &&
@@ -44,6 +55,11 @@ def cropping?(attachment_name)
       end
 
 
+      # Returns a Paperclip::Geometry object from a named attachment
+      #
+      # @param attachment_name [Symbol] 
+      # @param style [Symbol] attachment style, :original by default
+      # @return Paperclip::Geometry
       def image_geometry(attachment_name, style = :original)
         @geometry        ||= {}
         @geometry[style] ||= Paperclip::Geometry.from_file(self.send(attachment_name).path(style))
@@ -62,6 +78,7 @@ def method_missing(method, *args)
 
       private
 
+        # Reprocess the attachment after cropping
         def reprocess_cropped_attachment(attachment_name)
           self.send(attachment_name.to_sym).reprocess! if cropping? attachment_name
         end

lib/papercrop/helpers.rb

@@ -1,6 +1,15 @@
 module Papercrop
   module Helpers
 
+    # Form helper to render the cropping preview box of an attachment.
+    # Box width can be handled by setting the :width option. 
+    # Width is 100 by default. Height is calculated by the aspect ratio.
+    # 
+    #   crop_preview :avatar
+    #   crop_preview :avatar, :width => 150
+    #
+    # @param attachment [Symbol] attachment name
+    # @param opts [Hash]
     def crop_preview(attachment, opts = {})
       attachment = attachment.to_sym
       width      = opts[:width] || 100
@@ -19,6 +28,14 @@ def crop_preview(attachment, opts = {})
     end
 
 
+    # Form helper to render the main cropping box of an attachment.
+    # Loads the original image. Initially the cropbox has no limits on dimensions, showing the image at full size.
+    # You can restrict it by setting the :width option to the width you want.
+    #
+    #   cropbox :avatar, :width => 650
+    #
+    # @param attachment [Symbol] attachment name
+    # @param opts [Hash]
     def cropbox(attachment, opts = {})
       attachment      = attachment.to_sym
       original_width  = self.object.image_geometry(attachment, :original).width

papercrop.gemspec

@@ -7,12 +7,12 @@ Gem::Specification.new do |s|
   s.description   = "Paperclip extension for cropping images"
   s.authors       = ["Ruben Santamaria"]
   s.email         = '[email protected]'
-  s.homepage      = 'http://rubygems.org/gems/papercrop'
+  s.homepage      = 'https://github.com/rsantamaria/papercrop'
 
   s.files         = Dir.glob("{lib,vendor}/**/*") + %w(README.md)
   s.require_paths = ["lib"]
 
   s.add_dependency "rails", "~> 3.1"
   s.add_dependency "jquery-rails"
-  s.add_dependency "paperclip", "~> 3.1.3"
+  s.add_dependency "paperclip", "~> 3.1"
 end