Lots of new documentation, in better formatting for new opts

lib/squib/api/save.rb

@@ -1,23 +1,26 @@
 module Squib
   class Deck
 
-    # Saves the range of cards to either PNG or PDF
+    # Saves the given range of cards to either PNG or PDF
     #
-    # @param range: the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
-    # @param dir: the directory for the output to be sent to. Will be created if it doesn't exist
-    # @param format: the format that this will be rendered too. Options `:pdf, :png`. Array of both is allowed: `[:pdf, :png]`
-    # @param prefix: the prefix of the file name to be printed
+    # @option opts [Enumerable] range (:all) the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
+    # @option opts [String] dir (_output) the directory for the output to be sent to. Will be created if it doesn't exist.
+    # @option opts [Symbol] format (:png)  the format that this will be rendered too. Options `:pdf, :png`. Array of both is allowed: `[:pdf, :png]`
+    # @option opts [String] prefix (card_) the prefix of the file name to be printed
+    # @return self
+    # @api public
     def save(opts = {})
       opts = needs(opts, [:range, :creatable_dir, :formats, :prefix])
       save_png(opts) if opts[:format].include? :png
       save_pdf(opts) if opts[:format].include? :pdf
+      self
     end
 
-    # Saves the range of cards to PNG 
+    # Saves the given range of cards to PNG 
     #
-    # @param range: the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
-    # @param dir: the directory for the output to be sent to. Will be created if it doesn't exist
-    # @param prefix: the prefix of the file name to be printed
+    # @option opts [Enumerable] range (:all) the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
+    # @option opts [String] dir (_output) the directory for the output to be sent to. Will be created if it doesn't exist.
+    # @option opts [String] prefix (card_) the prefix of the file name to be printed.
     def save_png(opts = {})
       opts = needs(opts,[:range, :creatable_dir, :prefix])
       opts[:range].each do |i| 

lib/squib/api/shapes.rb

@@ -3,16 +3,17 @@ class Deck
 
     # Draw a rounded rectangle
     #
-    # @param x: the x-coordinate to place
-    # @param y: the y-coordinate to place
-    # @param width: the width of the rectangle.
-    # @param height: the height of the rectangle.
-    # @param x_radius: the radius of the rounded corner horiztonally. Zero is a non-rounded corner.
-    # @param y_radius: the radius of the rounded corner vertically. Zero is a non-rounded corner.
-    # @param radius: when set, overrides both x_radius and y_radius
-    # @param fill_color: the color with which to fill the rectangle
-    # @param stroke_color: the color with which to stroke the outside of the rectangle
-    # @param stroke_width: the width of the outside stroke
+    # @param opts: the hash of options.
+    # @option x: the x-coordinate to place
+    # @option y: the y-coordinate to place
+    # @option width: the width of the rectangle.
+    # @option height: the height of the rectangle.
+    # @option x_radius: the radius of the rounded corner horiztonally. Zero is a non-rounded corner.
+    # @option y_radius: the radius of the rounded corner vertically. Zero is a non-rounded corner.
+    # @option radius: when set, overrides both x_radius and y_radius
+    # @option fill_color: the color with which to fill the rectangle
+    # @option stroke_color: the color with which to stroke the outside of the rectangle
+    # @option stroke_width: the width of the outside stroke
     # @api public
     def rect(opts = {})
       opts = needs(opts, [:range, :x, :y, :width, :height, :radius, 

lib/squib/api/units.rb

@@ -3,7 +3,9 @@ class Deck
 
     # Given inches, returns the number of pixels according to the deck's DPI.
     # 
-    # @example inches(2.5) # 750px for 300 dpi
+    # @example 
+    #   inches(2.5) # 750 (for default Deck::dpi of 300)
+    #
     # @param [Decimal] n, the number of inches
     # @return [Decimal] the number of pixels, according to the deck's DPI
     # @api public