From 246b9df9fc90a95369d5576c9115f22908e24983 Mon Sep 17 00:00:00 2001
From: Andy Meneely <andy@se.rit.edu>
Date: Fri, 25 Jul 2014 09:27:22 -0400
Subject: [PATCH] Better documentation for text

---
 lib/squib/api/text.rb | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/lib/squib/api/text.rb b/lib/squib/api/text.rb
index b1dcc68..129da2f 100644
--- a/lib/squib/api/text.rb
+++ b/lib/squib/api/text.rb
@@ -12,7 +12,9 @@ module Squib
     end
 
     # Renders a string at a given location, width, alignment, font, etc.
-    #   Unix-like newlines are interpreted even on Windows. See the {file:samples/text-options.rb samples/text.rb} for a lengthy example.
+    #   Unix-like newlines are interpreted even on Windows. 
+    #
+    # @example See the {file:samples/text-options.rb samples/text.rb} for a lengthy example.
     # 
     # @param range: the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
     # @param str: the string to be rendered. Must support `#to_s`. If the card responds to `#each`, it's mapped out one at a time across the cards.
@@ -23,19 +25,20 @@ module Squib
     #   See the {file:samples/text-options.rb samples/text.rb} as well.
     # @param x: the x-coordinate to place
     # @param y: the y-coordinate to place
-    # @param color: (default: :black) the color the font will render to. See {file:API.md#label-Specifying+Colors Specifying Colors}
-    # @param markup: [Boolean] (default: 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).
-    # @param width: the width of the box the string will be placed in. Stretches to the content by default.
-    # @param height: the height of the box the string will be placed in. Stretches to the content by default.
-    # @param wrap: 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.    #   
+    # @param options: captures the additional input options below
+    # @option color: (default: :black) the color the font will render to. See {file:API.md#label-Specifying+Colors Specifying Colors}
+    # @option markup: [Boolean] (default: 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 width: the width of the box the string will be placed in. Stretches to the content by default.
+    # @option height: the height of the box the string will be placed in. Stretches to the content by default.
+    # @option wrap: 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`
-    # @param fitxy: sets the text `width` and `height` to be equal to `width - x` and `height - y` for easy centering
-    # @param align: options `:left, :right, and :center`. Default `:left`
-    # @param justify: [Boolean] toggles whether or not the text is justified or not. Default `false`
-    # @param valign: When width and height are set, align text vertically according to the logical extents of the text. Options are `:top, :middle, :bottom`. Default `:top`
-    # @param ellipsize: When width and height are set, determines the behavior of overflowing text. Options are `:none, :start, :middle, :end`. Also: `true` maps to `:end` and `false` maps to `:none`. Default `:end`
-    # @param hint: show a text hint with the given color. Overrides global hints (see {Deck#hint}). 
-    #
+    # @option fitxy: sets the text `width` and `height` to be equal to `width - x` and `height - y` for easy centering
+    # @option align: options `:left, :right, and :center`. Default `:left`
+    # @option justify: [Boolean] toggles whether or not the text is justified or not. Default `false`
+    # @option valign: When width and height are set, align text vertically according to the logical extents of the text. Options are `:top, :middle, :bottom`. Default `:top`
+    # @option ellipsize: When width and height are set, determines the behavior of overflowing text. Options are `:none, :start, :middle, :end`. Also: `true` maps to `:end` and `false` maps to `:none`. Default `:end`
+    # @option hint: show a text hint with the given color. Overrides global hints (see {Deck#hint}). 
+    # @return [nil] Returns nothing
     # @api public
     def text(range: :all, str: '', font: :use_set, x: 0, y: 0, **options)
       range = rangeify(range)