Tons of documentation work

lib/squib/api/background.rb

@@ -1,13 +1,11 @@
 module Squib
   class Deck
-    #module API
 
-      def background(range: :all, color: :black)
-        range = rangeify(range)
-        color = colorify(color)
-        range.each { |i| @cards[i].background(color) }
-      end
+    def background(range: :all, color: :black)
+      range = rangeify(range)
+      color = colorify(color)
+      range.each { |i| @cards[i].background(color) }
+    end
       
-    #end
   end
 end

lib/squib/api/data.rb

@@ -3,10 +3,18 @@ require 'roo'
 module Squib
   class Deck
 
+    #@api private todo
     def csv(file: 'deck.csv', header: true)
       raise 'Not implemented!'
     end
 
+    # Convenience method for pulling Excel data from `.xlsx` files
+    #   Pulls the data into a Hash of arrays based on the columns. First row is assumed to be the header row. 
+    #   See the example at {file:samples/excel.rb samples/excel.rb}. The accompanying Excel file is in the [source repository](https://github.com/andymeneely/squib/tree/master/samples)
+    #
+    # @param file: [String] the file to open. Must end in `.xlsx`. Opens relative to the current directory.
+    # @param sheet: [Integer] The zero-based index of the sheet from which to read.
+    # @api public
     def xlsx(file: 'deck.xlsx', sheet: 0)
       s = Roo::Excelx.new(file)
       s.default_sheet = s.sheets[sheet]

lib/squib/api/image.rb

@@ -1,12 +1,29 @@
 module Squib
   class Deck
     
+    # Renders a png file at the given location.
+    #   See {file:samples/image.rb samples/image.rb} and {file:samples/tgc-overlay.rb samples/tgc-overlay.rb} as examples.
+    #   Note: scaling not currently supported.
+    #
+    # @param range: the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
+    # @param file: the . See {file:API.md#Specifying+Files Specifying Files}
+    # @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
     def png(range: :all, file: nil, x: 0, y: 0, alpha: 1.0)
       range = rangeify(range)
       file = fileify(file)
       range.each{ |i| @cards[i].png(file, x, y, alpha) }
     end
 
+    # Renders an entire svg file at the given location. Uses the SVG-specified units and DPI to determine the pixel width and height.
+    #   See {file:samples/image.rb samples/image.rb} and {file:samples/tgc-overlay.rb samples/tgc-overlay.rb} as examples.
+    #   Note: scaling not currently supported.
+    #
+    # @param range: the range of cards over which this will be rendered. See {file:API.md#label-Specifying+Ranges Specifying Ranges}
+    # @param file: the . See {file:API.md#Specifying+Files Specifying Files}
+    # @param x: the x-coordinate to place
+    # @param y: the y-coordinate to place
     def svg(range: :all, file: nil, x: 0, y: 0)
       range = rangeify(range)
       file = fileify(file)

lib/squib/api/save.rb

@@ -1,12 +1,23 @@
 module Squib
   class Deck
   
+    # Saves the 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
     def save(range: :all, dir: "_output", format: :png, prefix: "card_")
       format = [format].flatten
       save_png(range: range, dir: dir, prefix: prefix) if format.include? :png
       save_pdf if format.include? :pdf
     end
     
+    # Saves the 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
     def save_png(range: :all, dir: "_output", prefix: 'card_')
       range = rangeify(range); dir = dirify(dir, allow_create: true)
       range.each { |i| @cards[i].save_png(i, dir, prefix) }

lib/squib/api/settings.rb

@@ -1,7 +1,15 @@
 module Squib
   class Deck
 
+    # Toggle hints globally. 
+    #   Text hints are rectangles around where the text will be laid out. They are intended to be temporary.
+    #   Setting a hint to nil or to :off will disable hints. @see samples/text.rb
+    #
+    # @param [Color] text the color of the text hint. To turn off use nil or :off. @see API.md 
+    # @return nil
+    # @api public
     def hint(text: nil)
+      text = nil if text == :off
       @text_hint = colorify(text, nillable: true)
     end
 

lib/squib/api/shapes.rb

@@ -2,9 +2,10 @@ module Squib
   class Deck
     
     def rect(range: :all, x: 0, y: 0, width: 825, height: 1125, \
-              x_radius: 0, y_radius: 0, color: :black)
+              radius: 0, x_radius: 0, y_radius: 0, color: :black)
       range = rangeify(range)
       color = colorify(color)
+      x_radius,y_radius = radiusify(radius, x_radius, y_radius)
       range.each do |i|
         @cards[i].draw_rectangle(x, y, width, height, x_radius, y_radius, color)
       end

lib/squib/api/text.rb

@@ -1,25 +1,48 @@
 module Squib
   class Deck
+
+    # @api private todo
     def font(type: 'Arial', size: 12, **options)
       raise 'Not implemented!'
     end
 
+    # @api private todo
     def set_font(type: 'Arial', size: 12, **options)
       raise 'Not implemented!'
     end
 
-    #
-    # font: description string, including family, styles, and size.
+    # 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.
     # 
-    # => e.g. 'Arial bold italic 12'
-    # For the official documentation the string, see the [Pango docs](http://ruby-gnome2.sourceforge.jp/hiki.cgi?Pango%3A%3AFontDescription#style). 
-    # This [description](http://www.pygtk.org/pygtk2reference/class-pangofontdescription.html) is also quite good.
+    # @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`.
+    # @param font: the Font description string, including family, styles, and size.
+    #   (e.g. `'Arial bold italic 12'`)
+    #   For the official documentation, see the [Pango docs](http://ruby-gnome2.sourceforge.jp/hiki.cgi?Pango%3A%3AFontDescription#style). 
+    #   This [description](http://www.pygtk.org/pygtk2reference/class-pangofontdescription.html) is also quite good.
+    #   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.    #   
+    #   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}). 
+    #
+    # @api public
     def text(range: :all, str: '', font: :use_set, x: 0, y: 0, **options)
       range = rangeify(range)
       str = [str] * @cards.size unless str.respond_to? :each
       font = fontify(font)
       color = colorify(options[:color], nillable: false)
-      options['hint'] = colorify(options['hint']) unless options['hint'].nil?
+      options[:hint] = colorify(options[:hint]) unless options[:hint].nil?
       range.each do |i|
         cards[i].text(str[i], font, x, y, color, options)
       end

lib/squib/api/units.rb

@@ -0,0 +1,14 @@
+module Squib
+  class Deck
+
+    # Given inches, returns the number of pixels according to the deck's DPI.
+    #
+    # @param [Decimal] n, the number of inches
+    # @return [Decimal] the number of pixels, according to the deck's DPI
+    # @api public
+    def inches(n)
+      @dpi * n
+    end
+
+  end
+end

lib/squib/constants.rb

@@ -1,7 +1,8 @@
 module Squib
   module Constants
 
-    DEFAULT_FONT = 'Arial 36'
+    #@api public
+    DEFAULT_FONT = 'Arial 36 B'
     
   end
 end

lib/squib/deck.rb

@@ -3,7 +3,15 @@ require 'squib/card'
 require 'squib/input_helpers'
 require 'squib/constants'
 
+
+# The project module
+#
+# @api public
 module Squib
+
+  # The main interface to Squib. Provides a front-end porcelain whereas the Card class interacts with the graphics plumbing.
+  #
+  # @api public
   class Deck
     include Enumerable
     include Squib::InputHelpers
@@ -12,9 +20,12 @@ module Squib
     attr_reader :cards
     attr_reader :text_hint
 
-    def initialize(width: 825, height: 1125, cards: 1, config: 'config.yml', &block)
+    # Squib's constructor that sets the immutable properties.
+    # 
+    # @api public
+    def initialize(width: 825, height: 1125, cards: 1, dpi: 300, config: 'config.yml', &block)
       @width=width; @height=height
-      @dpi = 300
+      @dpi = dpi
       @font = 'Sans 36'
       @cards = []
       cards.times{ @cards << Squib::Card.new(self, width, height) }
@@ -24,20 +35,21 @@ module Squib
       end
     end
 
-    # API: Accesses the array of cards in the deck
+    # Directly accesses the array of cards in the deck
+    #
     # @api public
     def [](key)
       @cards[key]
     end
 
-    # Public: Accesses each card of the array in the deck
-    # @api 
+    # Iterates over each card in the deck
+    # 
+    # @api public
     def each(&block)
       @cards.each { |card| block.call(card) }
     end
 
-    # Internal: Load the configuration file, if exists, 
-    # overriding hardcoded defaults
+    # Load the configuration file, if exists, overriding hardcoded defaults
     # @api private
     def load_config(file)
       if File.exists? file
@@ -57,6 +69,7 @@ module Squib
     require 'squib/api/settings'
     require 'squib/api/shapes'
     require 'squib/api/text'
+    require 'squib/api/units'
 
   end
 end

lib/squib/graphics/text.rb

@@ -34,6 +34,8 @@ module Squib
               :char => Pango::Layout::WRAP_CHAR,
               :word_char    => Pango::Layout::WRAP_WORD_CHAR,
               true    => Pango::Layout::WRAP_WORD_CHAR,
+              false => nil,
+              :none => nil
             }
         layout.wrap = h[options[:wrap]]
       end

lib/squib/input_helpers.rb

@@ -49,6 +49,16 @@ module Squib
     end
     module_function :fontify 
 
+    def radiusify(radius, x_radius, y_radius)
+      unless radius.nil?
+        ret_x = radius
+        ret_y = radius
+      end
+      ret_x = x_radius unless x_radius.nil?
+      rex_y = y_radius unless y_radius.nil?
+      return ret_x,ret_y
+    end
+
     def xyify
       #TODO: Allow negative numbers that subtract from the card width & height
     end