From 3f5adce4a6ac2c53442d66854c55923d0ba4a83a Mon Sep 17 00:00:00 2001
From: Andy Meneely <andy@se.rit.edu>
Date: Mon, 28 Jul 2014 16:16:01 -0400
Subject: [PATCH] Lots of new documentation, in better formatting for new opts

---
 lib/squib/api/save.rb   | 21 ++++++++++++---------
 lib/squib/api/shapes.rb | 21 +++++++++++----------
 lib/squib/api/units.rb  |  4 +++-
 3 files changed, 26 insertions(+), 20 deletions(-)

diff --git a/lib/squib/api/save.rb b/lib/squib/api/save.rb
index 9665dcd..c46c5c6 100644
--- a/lib/squib/api/save.rb
+++ b/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| 
diff --git a/lib/squib/api/shapes.rb b/lib/squib/api/shapes.rb
index c10179f..ef1987a 100644
--- a/lib/squib/api/shapes.rb
+++ b/lib/squib/api/shapes.rb
@@ -3,16 +3,17 @@ module Squib
     
     # 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, 
diff --git a/lib/squib/api/units.rb b/lib/squib/api/units.rb
index 5d566a5..7dfcbed 100644
--- a/lib/squib/api/units.rb
+++ b/lib/squib/api/units.rb
@@ -3,7 +3,9 @@ module Squib
 
     # 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