From e5a889a274a2ea684d295c51acb149a93eba3961 Mon Sep 17 00:00:00 2001
From: Andy Meneely <andy@se.rit.edu>
Date: Tue, 29 Jul 2014 17:16:19 -0400
Subject: [PATCH] Tons more documentation.

---
 API.md                     | 37 ++++++++++++++-----------------------
 lib/squib/api/image.rb     |  2 ++
 lib/squib/api/shapes.rb    |  1 +
 lib/squib/api/text.rb      |  1 +
 lib/squib/commands/new.rb  | 17 +++++++++++++++++
 lib/squib/constants.rb     | 19 ++++++++++---------
 lib/squib/input_helpers.rb | 10 ++++++++++
 lib/squib/version.rb       |  3 +++
 samples/use_layout.rb      |  6 +++---
 9 files changed, 61 insertions(+), 35 deletions(-)

diff --git a/API.md b/API.md
index d89ccfe..f888ccf 100644
--- a/API.md
+++ b/API.md
@@ -1,35 +1,20 @@
 # Squib API
 
-The Squib DSL is based on a collection of methods provided to the `Squib::Deck` class. The general philosophy of Squib is to specify as little as possible (i.e. great defaults )
+The Squib DSL is based on a collection of methods provided to the `Squib::Deck` class. The general philosophy of Squib is to specify as little as possible with layers of defaults, highly flexible input, and good ol' Ruby duck-typing. Ruby does a lot to make Squib useful.
 
 # Squib::Deck and Squib::Card
 
 Squib essentially has two main classes: `Deck` and `Card`. `Deck` is the front-end, and `Card` is the back-end. The contract of `Deck` is to do the various manipulations of options and then delegate the operation to `Card` to do the low-level graphical operations. 
 
-For most users, I recommending solely using `Deck` methods. If you want to roll up your sleeves and get your hands messy, you can access the Cairo or Pango contexts the directly via the `Card` class. 
+For most users, I recommending solely using `Deck` methods. If you want to roll up your sleeves and get your hands messy, you can access the Cairo or Pango contexts the directly via the `Card` class. The API documentation doesn't really cover these, however, so you're on your own there.
 
 # Specifying Parameters
 
-Squib makes extensive use of [Ruby 2.0's named parameters](http://www.ruby-doc.org/core-2.0.0/doc/syntax/calling_methods_rdoc.html#label-Keyword+Arguments). This means you can specify your parameters in any order you please. In fact, with named parameters you *must* specify which argument ties to which parameter. If you get an error like this:
-
-```cmd
-C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.2/lib/squib/api/text.rb:17:in `text': wrong number of arguments (1 for 0)
-(ArgumentError)
-        from hello-world.rb:5:in `block in <main>'
-        from C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.2/lib/squib/deck.rb:21:in `instance_eval'
-        from C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.2/lib/squib/deck.rb:21:in `initialize'
-        from hello-world.rb:4:in `new'
-        from hello-world.rb:4:in `<main>'
-```
-...then you're not specifying the parameters explicitly (e.g. the above example was with `text 'X'` instead of `text str: 'X'`)
-
-All parameters are optional. For example `x` and `y` default to 0 (i.e. the upper-left corner of the card).
-
-Any parameter that is specified in the command overrides any Squib defaults, `config.yml` settings, or layout rules. 
+Squib is all about sane defaults and shorthand specification. Arguments are almost always using hashes, which look a lot like [Ruby 2.0's named parameters](http://www.ruby-doc.org/core-2.0.0/doc/syntax/calling_methods_rdoc.html#label-Keyword+Arguments). This means you can specify your parameters in any order you please. All parameters are optional. For example `x` and `y` default to 0 (i.e. the upper-left corner of the card). Any parameter that is specified in the command overrides any Squib defaults, `config.yml` settings, or layout rules. 
 
 # Specifying Ranges
 
-Most public `Deck` methods allow a range to be specified as a first parameter. This parameter is used to access an internal `Array` of `Squib::Cards`. This can be an actual Ruby range, or anything that implements `#each` (thus can be an `Enumerable`). Integers are also supported for changing one card only. Negatives work from the back of the deck. Here are some examples from `samples/ranges.rb` found [here](https://github.com/andymeneely/squib/tree/master/samples/ranges.rb)
+Most public `Deck` methods allow a `range` to be specified as a first parameter. This parameter is used to access an internal `Array` of `Squib::Cards`. This can be an actual Ruby range, or anything that implements `#each` (thus can be an `Enumerable`). Integers are also supported for changing one card only. Negatives work from the back of the deck. Here are some examples from `samples/ranges.rb` found [here](https://github.com/andymeneely/squib/tree/master/samples/ranges.rb)
 
 {include:file:samples/ranges.rb}
 
@@ -47,7 +32,7 @@ Colors can be specified in a wide variety of ways, mostly in a hex-string. Take
 
 {include:file:samples/colors.rb}
 
-Under the hood, Squib uses the `rcairo` [color parser](https://github.com/rcairo/rcairo/blob/master/lib/cairo/color.rb) to accepts a variety of color specifications, along with over [300 pre-defined constants](https://github.com/rcairo/rcairo/blob/master/lib/cairo/colors.rb). 
+Under the hood, Squib uses the `rcairo` [color parser](https://github.com/rcairo/rcairo/blob/master/lib/cairo/color.rb) to accept a variety of color specifications, along with over [300 pre-defined constants](https://github.com/rcairo/rcairo/blob/master/lib/cairo/colors.rb). 
 
 # Specifying Files
 
@@ -55,14 +40,20 @@ All files opened for reading or writing (e.g. for `png` and `xlsx`) are opened r
 
 # Custom Layouts
 
-Working with x-y coordinates can be tiresome, and ideally everything in a game prototype should be data-driven. To counter this, many Squib methods allow for a `layout` to be set. In essence, layouts are a way of setting default values for `x, y, width` and `height`. 
+Working with x-y coordinates all the time can be tiresome, and ideally everything in a game prototype should be data-driven and easily changed. For this, many Squib methods allow for a `layout` to be set. In essence, layouts are a way of setting default values for any argument given to the command. 
 
 To use a layout, set the `layout:` option on a `Deck.new` command to point to a YAML file. Any command that allows a `layout` option can be set with a Ruby symbol or String, and the command will then load the specified `x`, `y`, `width`, and `height`. The individual command can also override these options. 
 
 Note: YAML is very finnicky about having tabs in the file. Use two spaces for indentation instead.
 
-See the `use_layout` sample found [here](https://github.com/andymeneely/squib/tree/master/samples/)
+Layouts will override Squib's defaults, but are overriden by anything specified in the command itself. Thus, the order of precedence looks like this:
 
-{include:file:samples/use_layout.rb}
+* Use what the command specified
+* If anything was not yet specified, use what was given in a layout (if a layout was specified in the command and the file was given to the Deck)
+* If still anything was not yet specified, use what was given in Squib's defaults.
+
+Layouts also allow for a special `extends` field that will copy all of the settings from another entry. Only a single level of extends are supported currently (contact the developer if you want multiple levels). 
 
+See the `use_layout` sample found [here](https://github.com/andymeneely/squib/tree/master/samples/)
 
+{include:file:samples/use_layout.rb}
diff --git a/lib/squib/api/image.rb b/lib/squib/api/image.rb
index 8171bdf..c0d5205 100644
--- a/lib/squib/api/image.rb
+++ b/lib/squib/api/image.rb
@@ -12,6 +12,7 @@ module Squib
     # @option opts file [String, Array] ('') file(s) to read in. If it's a single file, then it's use for every card in range. If the parameter is an Array of files, then each file is looked up for each card. See {file:API.md#Specifying+Files Specifying Files}
     # @option opts x [Integer] (0) the x-coordinate to place
     # @option opts y [Integer] (0) the y-coordinate to place
+    # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:API.md#label-Custom+Layouts Custom Layouts}
     # @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image
     # @return [nil] Returns nil
     # @api public
@@ -34,6 +35,7 @@ module Squib
     # @option opts y [Integer] (0) the y-coordinate to place
     # @option opts width [Integer] (:native) 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.
     # @option opts height [Integer] (:native) 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.
+    # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:API.md#label-Custom+Layouts Custom Layouts}
     # @return [nil] Returns nil
     # @api public
     def svg(opts = {})
diff --git a/lib/squib/api/shapes.rb b/lib/squib/api/shapes.rb
index e3044eb..2fbad69 100644
--- a/lib/squib/api/shapes.rb
+++ b/lib/squib/api/shapes.rb
@@ -17,6 +17,7 @@ module Squib
     # @option opts fill_color [String] ('#0000') the color with which to fill the rectangle
     # @option opts stroke_color [String] (:black) the color with which to stroke the outside of the rectangle
     # @option opts stroke_width [Decimal] (2.0) the width of the outside stroke
+    # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:API.md#label-Custom+Layouts Custom Layouts}
     # @return [nil] intended to be void
     # @api public
     def rect(opts = {})
diff --git a/lib/squib/api/text.rb b/lib/squib/api/text.rb
index 96b5b84..698be0c 100644
--- a/lib/squib/api/text.rb
+++ b/lib/squib/api/text.rb
@@ -23,6 +23,7 @@ module Squib
     # @option opts markup: [Boolean] (false) Enable markup parsing of `str` using the HTML-like Pango Markup syntax, defined [here](http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup) and [here](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html).
     # @option opts width [Integer, :native] (:native) the width of the box the string will be placed in. Stretches to the content by default.
     # @option opts height [Integer, :native] the height of the box the string will be placed in. Stretches to the content by default.
+    # @option opts layout [String, Symbol] (nil) entry in the layout to use as defaults for this command. See {file:API.md#label-Custom+Layouts Custom Layouts}
     # @option opts wrap [:none, :word, :char, :word_char, true, false] (:word_char) When height is set, determines the behavior of how the string wraps. The `:word_char` option will break at words, but then fall back to characters when the word cannot fit.    #   
     #   Options are `:none, :word, :char, :word_char`. Also: `true` is the same as `:word_char`, `false` is the same as `:none`. Default `:word_char`
     # @option opts align [:left, right, :center] (:left) The alignment of the text
diff --git a/lib/squib/commands/new.rb b/lib/squib/commands/new.rb
index 6b8063e..1dda5e9 100644
--- a/lib/squib/commands/new.rb
+++ b/lib/squib/commands/new.rb
@@ -1,7 +1,24 @@
 module Squib
+  # Squib's command-line options
   module Commands
+
+    # Generate a new Squib project into a fresh directory.
+    #
+    # Provides conventions for using Git (you are using version control, right??). 
+    # Also provides some basic layout and config files to start from, along with templates for instructions and other notes you don't want to forget.
+    # 
+    #
+    # @example
+    #   squib new foo-blasters
+    #   cd foo-blasters
+    #   ruby deck.rb
+    #   git commit -am "Starting my cool new game using Squib!"
+    #
+    # @api public
     class New
 
+      # :nodoc:
+      # @api private 
       def process(args)
         raise ArgumentError.new('Please specify a path.') if args.empty?
 
diff --git a/lib/squib/constants.rb b/lib/squib/constants.rb
index d22bc33..259e947 100644
--- a/lib/squib/constants.rb
+++ b/lib/squib/constants.rb
@@ -1,18 +1,19 @@
 module Squib
-    
-    #@api public
+    # Squib's defaults for when arguments are not specified in the command nor layouts.
+    # 
+    # @api public
     SYSTEM_DEFAULTS = { 
-   		:range => :all,
-   		:color => :black,
+      :range => :all,
+      :color => :black,
       :str => '',
       :fill_color => '#0000',
       :stroke_color => :black,
       :stroke_width => 2.0,
-   		:font => :use_set,
+      :font => :use_set,
       :default_font => 'Arial 36',
-   		:sheet => 0,
-   		:x => 0,
-   		:y => 0,
+      :sheet => 0,
+      :x => 0,
+      :y => 0,
       :x1 => 100,
       :y1 => 100,
       :x2 => 150,
@@ -27,7 +28,7 @@ module Squib
       :ellipsize => :end,
       :width => :native,
       :height => :native,
-   		:alpha => 1.0,
+      :alpha => 1.0,
       :format => :png,
       :dir => "_output",
       :prefix => "card_",
diff --git a/lib/squib/input_helpers.rb b/lib/squib/input_helpers.rb
index 8538c83..50c6b30 100644
--- a/lib/squib/input_helpers.rb
+++ b/lib/squib/input_helpers.rb
@@ -5,6 +5,7 @@ module Squib
   # @api private
   module InputHelpers
 
+    # :nodoc:
     # @api private
     def needs(opts, params)
       opts = layoutify(opts) if params.include? :layout
@@ -25,6 +26,7 @@ module Squib
     end
     module_function :needs
 
+    # :nodoc:
     # @api private
     def layoutify(opts)
       unless opts[:layout].nil?
@@ -41,6 +43,7 @@ module Squib
     end
     module_function :layoutify
 
+    # :nodoc:
     # @api private
     def formatify(opts)
       opts[:format] = [opts[:format]].flatten
@@ -48,6 +51,7 @@ module Squib
     end
     module_function :formatify
 
+    # :nodoc:
     # @api private
     def rangeify (opts)
       range = opts[:range]
@@ -62,6 +66,7 @@ module Squib
     end
     module_function :rangeify
 
+    # :nodoc:
     # @api private
     def fileify(opts, expand_singletons=false, allow_non_exist=false)
       opts[:file] = [opts[:file]] * @cards.size if expand_singletons
@@ -75,6 +80,7 @@ module Squib
     end
     module_function :fileify
 
+    # :nodoc:
     # @api private
     def dirify(opts, allow_create=false)
       return opts if Dir.exists?(opts[:dir])
@@ -88,6 +94,7 @@ module Squib
     end
     module_function :dirify
 
+    # :nodoc:
     # @api private
     def colorify(opts, nillable=false)
       if nillable # for optional color arguments like text hints
@@ -99,6 +106,7 @@ module Squib
     end
     module_function :colorify
 
+    # :nodoc:
     # @api private
     def fontify (opts)
       opts[:font] = @font if opts[:font]==:use_set
@@ -107,6 +115,7 @@ module Squib
     end
     module_function :fontify 
 
+    # :nodoc:
     # @api private
     def radiusify(opts)
       unless opts[:radius].nil?
@@ -117,6 +126,7 @@ module Squib
     end
     module_function :radiusify
 
+    # :nodoc:
     # @api private
     def svgidify(opts)
       unless opts[:id].nil?
diff --git a/lib/squib/version.rb b/lib/squib/version.rb
index f9e536d..51f04be 100644
--- a/lib/squib/version.rb
+++ b/lib/squib/version.rb
@@ -1,3 +1,6 @@
 module Squib
+
+  # The next version to be released.
+  # Uses semantic versioning
   VERSION = "0.0.2"
 end
diff --git a/samples/use_layout.rb b/samples/use_layout.rb
index 5d13b13..4775013 100644
--- a/samples/use_layout.rb
+++ b/samples/use_layout.rb
@@ -10,7 +10,7 @@ Squib::Deck.new(layout: 'custom-layout.yml') do
   # You can also override a given layout entry in the command
   circle layout: :frame, x: 50, y: 50, radius: 25
 
-  # Any command with x-y-width-height options, we can use a custom layout
+  # Lots of commands have the :layout option
   text str: 'The Title', layout: :title
 
   # Layouts also support an "extends" attribute to reuse settings
@@ -22,8 +22,8 @@ Squib::Deck.new(layout: 'custom-layout.yml') do
   text str: 'subtitle', layout: 'subtitle'
 
   # For debugging purposes, you can always print out the loaded layout
-  # require 'pp'
-  # pp @layout
+  #require 'pp'
+  #pp @layout
 
   save_png prefix: 'layout_'
 end
\ No newline at end of file