pre-release prep

clean up .yardops and basic documentation for serialization helpers

11 files changed, 74 insertions, 21 deletions

diff --git a/.yardopts b/.yardopts
index 9ca191e5..d726ddfd 100644
--- a/.yardopts
+++ b/.yardopts
@@ -1,5 +1,8 @@
 --protected
 --no-private
 --title "AXLSX"
---files LICENSE
---files CHANGELOG.md
+--readme README.md
+--markup markdown
+--markup-provider kramdown
+--files CHANGELOG.md, LICENSE
+--list-undoc
diff --git a/README.md b/README.md
index 8470aa2f..a3b8182c 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ Axlsx: Office Open XML Spreadsheet Generation
 
 **Rubinius Version**: rubinius 2.0.0dev * lower versions may run, this gem always tests against head.
 
-**Release Date**: August 3rd 2012
+**Release Date**: August 4th 2012
 
 If you are working in rails, or with active record see:
 * http://github.com/randym/acts_as_xlsx
@@ -145,7 +145,8 @@ This gem has 100% test coverage using test/unit. To execute tests for this gem,
 
 #Change log
 ---------
-- **August.3.12**: 1.2.0
+- **August.4.12**: 1.2.0
+   - rebuilt worksheet serialization to clean up the code base a bit.
    - added data labels for charts
    - added table header printing for each sheet via defined_name. This
      means that when you print your worksheet, the header rows show for every page
diff --git a/axlsx.gemspec b/axlsx.gemspec
index 0ff87ae8..81a3ce0a 100644
--- a/axlsx.gemspec
+++ b/axlsx.gemspec
@@ -1,6 +1,6 @@
 # This will recursively require rake when using rake 0.9.2.2 and bundler
 #require 'rake'
-require File.expand_path(File.dirname(__FILE__) + '/lib/axlsx/version.rb')
+require File.expand_path('../lib/axlsx/version', __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = 'axlsx'
@@ -24,7 +24,7 @@ Gem::Specification.new do |s|
 
 # This has been removed until JRuby can support the native extensions for redcarpet or yard removes the dependency
   s.add_development_dependency 'yard'
-#  s.add_development_dependency 'redcarpet', '~>1.17.2'
+  s.add_development_dependency 'kramdown'
   s.add_development_dependency 'cover_me' unless RUBY_VERSION == '1.8.7'
   s.required_ruby_version = '>= 1.8.7'
   s.require_path = 'lib'
diff --git a/lib/axlsx/drawing/d_lbls.rb b/lib/axlsx/drawing/d_lbls.rb
index 54f054fb..531c5674 100644
--- a/lib/axlsx/drawing/d_lbls.rb
+++ b/lib/axlsx/drawing/d_lbls.rb
@@ -51,7 +51,7 @@ module Axlsx
     # Allowed positions are :bestFilt, :b, :ctr, :inBase, :inEnd, :l,
     # :outEnd, :r and :t
     # The default is :bestFit
-    # @param [Symbol] label_postion the postion you want to use.
+    # @param [Symbol] label_position the postion you want to use.
     def d_lbl_pos=(label_position)
       return unless @chart_type == Pie3DChart
       Axlsx::RestrictionValidator.validate 'DLbls#d_lbl_pos',  [:bestFit, :b, :ctr, :inBase, :inEnd, :l, :outEnd, :r, :t], label_position
diff --git a/lib/axlsx/version.rb b/lib/axlsx/version.rb
index ab15542f..4bffcb8d 100644
--- a/lib/axlsx/version.rb
+++ b/lib/axlsx/version.rb
@@ -1,10 +1,5 @@
 # encoding: UTF-8
 module Axlsx
-
-  # The version of the gem
-  # When using bunle exec rake and referencing the gem on github or locally
-  # it will use the gemspec, which preloads this constant for the gem's version.
-  # We check to make sure that it has not already been loaded
-  VERSION="1.2.0" unless defined? Axlsx::VERSION
-
+  # The current version
+  VERSION="1.2.0"
 end
diff --git a/lib/axlsx/workbook/worksheet/protected_ranges.rb b/lib/axlsx/workbook/worksheet/protected_ranges.rb
index e55d35fa..1231d752 100644
--- a/lib/axlsx/workbook/worksheet/protected_ranges.rb
+++ b/lib/axlsx/workbook/worksheet/protected_ranges.rb
@@ -12,6 +12,8 @@ module Axlsx
       @worksheet = worksheet
     end
 
+    # Adds a protected range
+    # @param [Array|String] cells A string range reference or array of cells that will be protected
     def add_range(cells)
      sqref = if cells.is_a?(String)
                cells
diff --git a/lib/axlsx/workbook/worksheet/sheet_data.rb b/lib/axlsx/workbook/worksheet/sheet_data.rb
index 98354b29..f9297711 100644
--- a/lib/axlsx/workbook/worksheet/sheet_data.rb
+++ b/lib/axlsx/workbook/worksheet/sheet_data.rb
@@ -3,6 +3,8 @@ module Axlsx
   # This class manages the serialization of rows for worksheets
   class SheetData
 
+    # Creates a new SheetData object
+    # @param [Worksheet] worksheet The worksheet that owns this sheet data.
     def initialize(worksheet)
       raise ArgumentError, "you must provide a worksheet" unless worksheet.is_a?(Worksheet)
       @worksheet = worksheet
@@ -10,6 +12,9 @@ module Axlsx
     
     attr_reader :worksheet
 
+    # Serialize the sheet data
+    # @param [String] str the string this objects serializaton will be concacted to.
+    # @return [String]
     def to_xml_string(str = '')
       str << '<sheetData>'
       worksheet.rows.each_with_index{ |row, index| row.to_xml_string(index, str) }
diff --git a/lib/axlsx/workbook/worksheet/sheet_pr.rb b/lib/axlsx/workbook/worksheet/sheet_pr.rb
index a7f54f28..6f03bf5b 100644
--- a/lib/axlsx/workbook/worksheet/sheet_pr.rb
+++ b/lib/axlsx/workbook/worksheet/sheet_pr.rb
@@ -1,6 +1,11 @@
 module Axlsx
+
+  # The SheetPr class manages serialization fo a worksheet's sheetPr element.
+  # Only fit_to_page is implemented
   class SheetPr
 
+    # Creates a new SheetPr object
+    # @param [Worksheet] worksheet The worksheet that owns this SheetPr object
     def initialize(worksheet)
       raise ArgumentError, "you must provide a worksheet" unless worksheet.is_a?(Worksheet)
       @worksheet = worksheet
@@ -8,6 +13,9 @@ module Axlsx
 
     attr_reader :worksheet
 
+    # Serialize the object
+    # @param [String] str serialized output will be appended to this object if provided.
+    # @return [String]
     def to_xml_string(str = '')
        return unless worksheet.fit_to_page?
       str << "<sheetPr><pageSetUpPr fitToPage=\"%s\"></pageSetUpPr></sheetPr>" % worksheet.fit_to_page?
diff --git a/lib/axlsx/workbook/worksheet/worksheet.rb b/lib/axlsx/workbook/worksheet/worksheet.rb
index abb6d48b..197e77c8 100644
--- a/lib/axlsx/workbook/worksheet/worksheet.rb
+++ b/lib/axlsx/workbook/worksheet/worksheet.rb
@@ -29,6 +29,8 @@ module Axlsx
       end
     end
 
+    # Initalizes page margin, setup and print options
+    # @param [Hash] options Options passed in from the initializer
     def initialize_page_options(options)
       @page_margins = PageMargins.new options[:page_margins] if options[:page_margins]
       @page_setup = PageSetup.new options[:page_setup]  if options[:page_setup]
@@ -68,7 +70,9 @@ module Axlsx
     def tables
       @tables ||=  Tables.new self
     end
-
+    
+    # The a shortcut to the worksheet_comments list of comments
+    # @return [Array|SimpleTypedList]
     def comments
       worksheet_comments.comments if worksheet_comments.has_comments?
     end
@@ -265,7 +269,7 @@ module Axlsx
 
     # The name of the worksheet
     # The name of a worksheet must be unique in the workbook, and must not exceed 31 characters
-    # @param [String] v
+    # @param [String] name 
     def name=(name)
       validate_sheet_name name
       @name=Axlsx::coder.encode(name)
diff --git a/lib/axlsx/workbook/worksheet/worksheet_comments.rb b/lib/axlsx/workbook/worksheet/worksheet_comments.rb
index 25ddb024..8c700aa0 100644
--- a/lib/axlsx/workbook/worksheet/worksheet_comments.rb
+++ b/lib/axlsx/workbook/worksheet/worksheet_comments.rb
@@ -1,35 +1,54 @@
 module Axlsx
 
-  #A wraper class for comments that defines its on worksheet
-  #serailization
+  # A wraper class for comments that defines its on worksheet
+  # serailization
   class WorksheetComments
 
+    # Creates a new WorksheetComments object
+    # param [Worksheet] worksheet The worksheet comments in thes object belong to
     def initialize(worksheet)
       raise ArugumentError, 'You must provide a worksheet' unless worksheet.is_a?(Worksheet)
       @worksheet = worksheet
     end
+
     attr_reader :worksheet
 
+    # The comments for this worksheet.
+    # @return [Comments]
     def comments
       @comments ||= Comments.new(worksheet)
     end
 
+    # Adds a comment
+    # @param [Hash] options
+    # @see Comments#add_comment
     def add_comment(options={})
       comments.add_comment(options)
     end 
 
+    # The relationships defined by this objects comments collection
+    # @return [Relationships]
     def relationships
       return [] unless has_comments?
       comments.relationships
     end
 
+
+    # Helper method to tell us if there are comments in the comments collection
+    # @return [Boolean]
     def has_comments?
       !comments.empty?
     end
 
+    # The index in the worksheet's relationships for the VML drawing that will render the comments
+    # @return [Integer]
     def index
       worksheet.relationships.index { |r| r.Type == VML_DRAWING_R } + 1
     end
+
+    # Seraalize the object
+    # @param [String] str
+    # @return [String]
     def to_xml_string(str = '')
       return unless has_comments?
       str << "<legacyDrawing r:id='rId#{index}' />"
diff --git a/lib/axlsx/workbook/worksheet/worksheet_drawing.rb b/lib/axlsx/workbook/worksheet/worksheet_drawing.rb
index 56131540..6ace16e1 100644
--- a/lib/axlsx/workbook/worksheet/worksheet_drawing.rb
+++ b/lib/axlsx/workbook/worksheet/worksheet_drawing.rb
@@ -6,6 +6,8 @@ module Axlsx
   # worksheet
   class WorksheetDrawing
 
+    # Creates a new WorksheetDrawing
+    # @param [Worksheet] worksheet
     def initialize(worksheet)
       raise ArgumentError, 'you must provide a worksheet' unless worksheet.is_a?(Worksheet)
       @worksheet = worksheet      
@@ -13,18 +15,28 @@ module Axlsx
     end
 
     attr_reader :worksheet
-    attr_reader :drawing
 
+    attr_reader :drawing
+    
+    # adds a chart to the drawing object
+    # @param [Class] chart_type The type of chart to add
+    # @param [Hash] options Options to pass on to the drawing and chart
+    # @see Worksheet#add_chart
     def add_chart(chart_type, options)
       @drawing ||= Drawing.new worksheet
       drawing.add_chart(chart_type, options)
     end
-   
+    
+    # adds an image to the drawing object
+    # @param [Hash] options Options to pass on to the drawing and image 
+    # @see Worksheet#add_image
     def add_image(options)
       @drawing ||= Drawing.new worksheet
       drawing.add_image(options)
     end 
-   
+  
+    # helper method to tell us if the drawing has something in it or not
+    # @return [Boolean] 
     def has_drawing?
       @drawing.is_a? Drawing
     end
@@ -36,10 +48,14 @@ module Axlsx
       Relationship.new(DRAWING_R, "../#{drawing.pn}") 
     end
 
+    # returns the index of the worksheet releationship that defines this drawing.
+    # @return [Integer]
     def index
        worksheet.relationships.index{ |r| r.Type == DRAWING_R } +1 
     end
 
+    # Serialize the drawing for the worksheet
+    # @param [String] str
     def to_xml_string(str = '')
       return unless has_drawing? 
       str << "<drawing r:id='rId#{index}'/>"