diff --git a/README.md b/README.md
index 2f12d4d..cc5e208 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,11 @@ end
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Install it yourself with:
+
+    $ gem install squib
+
+If you're using Bundler, add this line to your application's Gemfile:
 
     gem 'squib'
 
@@ -28,11 +32,7 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
-
-    $ gem install squib
-
-Note: Squib has some native dependencies, such as [Cairo](https://github.com/rcairo/rcairo), [Pango](http://ruby-gnome2.sourceforge.jp/hiki.cgi?Pango%3A%3ALayout), and [Nokogiri](http://nokogiri.org/), which all require DevKit to compile C code. This is usually not painful, but on some setups can cause headaches. For Windows users, I *strongly* recommend using the *non-*64 bit RubyInstaller at http://rubyinstaller.org/
+Note: Squib has some native dependencies, such as [Cairo](https://github.com/rcairo/rcairo), [Pango](http://ruby-gnome2.sourceforge.jp/hiki.cgi?Pango%3A%3ALayout), and [Nokogiri](http://nokogiri.org/), which all require DevKit to compile C code. This is usually not painful, but on some setups can cause headaches. For Windows users, I *strongly* recommend using the *non-*64 bit RubyInstaller at http://rubyinstaller.org. For Mac, I recommend using [rvm](https://rvm.io).
 
 ## Getting Started
 
@@ -45,6 +45,7 @@ $ ruby deck.rb
 ```
 
 The `squib new` command will generate files and folders like this:
+
 ```
 _output
   gitkeep.txt
@@ -80,7 +81,7 @@ end
 ## Learning Squib's API
 
 * The `samples` directory in the [source repository](https://github.com/andymeneely/squib) has lots of examples
-* The [API.md]() walks through the various methods and options
+* The document called API.md walks through the various methods and options that apply to the entire Squib API
 * [API Documentation](http://rubydoc.info/gems/squib/) is also kept up-to-date.
 
 ## Development
diff --git a/lib/squib/api/background.rb b/lib/squib/api/background.rb
index d05ecc7..d7e0df3 100644
--- a/lib/squib/api/background.rb
+++ b/lib/squib/api/background.rb
@@ -1,7 +1,11 @@
 module Squib
   class Deck
-
-    def background(range: :all, color: :black)
+    # Fills the background with the given color 
+    #
+    # @param range: the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
+    # @param color: the color the font will render to. See {file:API.md#label-Specifying+Colors Specifying Colors}
+    # @api public
+    def background(range: :all, color: :white)
       range = rangeify(range)
       color = colorify(color)
       range.each { |i| @cards[i].background(color) }
diff --git a/lib/squib/api/image.rb b/lib/squib/api/image.rb
index 1381f5a..2d64d26 100644
--- a/lib/squib/api/image.rb
+++ b/lib/squib/api/image.rb
@@ -10,6 +10,7 @@ module Squib
     # @param x: the x-coordinate to place
     # @param y: the y-coordinate to place
     # @param alpha: the alpha-transparency percentage used to blend this image
+    # @api public
     def png(range: :all, file: nil, x: 0, y: 0, alpha: 1.0)
       range = rangeify(range)
       file = fileify(file)
@@ -25,6 +26,7 @@ module Squib
     # @param y: the y-coordinate to place
     # @param width: the pixel width that the image should scale to. SVG scaling is done with vectors, so the scaling should be smooth. When set to `:native`, uses the DPI and units of the loaded SVG document.
     # @param height: the pixel width that the image should scale to. SVG scaling is done with vectors, so the scaling should be smooth. When set to `:native`, uses the DPI and units of the loaded SVG document.
+    # @api public
     def svg(range: :all, file: nil, x: 0, y: 0, width: :native, height: :native)
       range = rangeify(range)
       file = fileify(file)
diff --git a/lib/squib/api/shapes.rb b/lib/squib/api/shapes.rb
index b60b50d..e77f5d6 100644
--- a/lib/squib/api/shapes.rb
+++ b/lib/squib/api/shapes.rb
@@ -1,6 +1,19 @@
 module Squib
   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
+    # @api public
     def rect(range: :all, x: 0, y: 0, width: 825, height: 1125, \
               radius: nil, x_radius: 0, y_radius: 0, \
               fill_color: '#0000', stroke_color: :black, stroke_width: 2.0)