Add documentation

Author: chrahunt

.gitignore

@@ -2,3 +2,4 @@
 .bundle
 Gemfile.lock
 pkg/*
+doc/

lib/docx/containers/container.rb

@@ -1,20 +1,20 @@
-require 'docx/elements'
-
-module Docx
-  module Elements
-    module Containers
-      module Container
-        # Relation methods
-        # TODO: Create a properties object, include Element
-        def properties
-          @node.at_xpath("./#{@properties_tag}")
-        end
-
-        # TODO: Maybe merge and then clear so there is only one text node left.
-        def blank!
-          @node.xpath(".//w:t").each {|t| t.content = '' }
-        end
-      end
-    end
-  end
+require 'docx/elements'
+
+module Docx
+  module Elements
+    module Containers
+      module Container
+        # Relation methods
+        # TODO: Create a properties object, include Element
+        def properties
+          @node.at_xpath("./#{@properties_tag}")
+        end
+
+        # Erase text within an element
+        def blank!
+          @node.xpath(".//w:t").each {|t| t.content = '' }
+        end
+      end
+    end
+  end
 end

lib/docx/containers/paragraph.rb

@@ -1,50 +1,53 @@
-require 'docx/containers/text_run'
-require 'docx/containers/container'
-
-module Docx
-  module Elements
-    module Containers
-      class Paragraph
-        include Container
-        include Elements::Element
-
-        TAG = 'p'
-
-        # Child elements: pPr, r, fldSimple, hlink, subDoc
-        # http://msdn.microsoft.com/en-us/library/office/ee364458(v=office.11).aspx
-        def initialize(node)
-          @node = node
-          @properties_tag = 'pPr'
-        end
-
-        # Handle direct text insertion into paragraph on some conditions
-        def text=(content)
-          if text_runs.size == 1
-            text_runs.first.text = content
-          elsif text_runs.size == 0
-            new_r = TextRun.create_within(self)
-            new_r.text = content
-          else
-            text_runs.each {|r| r.node.remove }
-            new_r = TextRun.create_within(self)
-            new_r.text = content
-          end
-        end
-
-        def to_s
-          text_runs.map(&:text).join('')
-        end
-
-        def text_runs
-          @node.xpath('w:r').map {|r_node| Containers::TextRun.new(r_node) }
-        end
-
-        def each_text_run
-          text_runs.each { |tr| yield(tr) }
-        end
-        
-        alias_method :text, :to_s
-      end
-    end
-  end
-end
+require 'docx/containers/text_run'
+require 'docx/containers/container'
+
+module Docx
+  module Elements
+    module Containers
+      class Paragraph
+        include Container
+        include Elements::Element
+
+        TAG = 'p'
+
+        # Child elements: pPr, r, fldSimple, hlink, subDoc
+        # http://msdn.microsoft.com/en-us/library/office/ee364458(v=office.11).aspx
+        def initialize(node)
+          @node = node
+          @properties_tag = 'pPr'
+        end
+
+        # Set text of paragraph
+        def text=(content)
+          if text_runs.size == 1
+            text_runs.first.text = content
+          elsif text_runs.size == 0
+            new_r = TextRun.create_within(self)
+            new_r.text = content
+          else
+            text_runs.each {|r| r.node.remove }
+            new_r = TextRun.create_within(self)
+            new_r.text = content
+          end
+        end
+
+        # Return text of paragraph
+        def to_s
+          text_runs.map(&:text).join('')
+        end
+
+        # Array of text runs contained within paragraph
+        def text_runs
+          @node.xpath('w:r').map {|r_node| Containers::TextRun.new(r_node) }
+        end
+
+        # Iterate over each text run within a paragraph
+        def each_text_run
+          text_runs.each { |tr| yield(tr) }
+        end
+        
+        alias_method :text, :to_s
+      end
+    end
+  end
+end

lib/docx/containers/text_run.rb

@@ -1,68 +1,70 @@
-require 'docx/containers/container'
-
-module Docx
-  module Elements
-    module Containers
-      class TextRun
-        include Container
-        include Elements::Element
-
-        DEFAULT_FORMATTING = {
-          italic:    false,
-          bold:      false,
-          underline: false
-        }
-        
-        TAG = 'r'
-
-        attr_reader :text
-        attr_reader :formatting
-        
-        def initialize(node)
-          @node = node
-          @text_nodes = @node.xpath('w:t').map {|t_node| Elements::Text.new(t_node) }
-          @properties_tag = 'rPr'
-          @text       = parse_text || ''
-          @formatting = parse_formatting || DEFAULT_FORMATTING
-        end
-
-        def text=(content)
-          if @text_nodes.size == 1
-            @text_nodes.first.content = content
-          elsif @text_nodes.empty?
-            new_t = Elements::Text.create_within(self)
-            new_t.content = content
-          end
-        end
-
-        def parse_text
-          @text_nodes.map(&:content).join('')
-        end
-
-        def parse_formatting
-          {
-            italic:    !@node.xpath('.//w:i').empty?,
-            bold:      !@node.xpath('.//w:b').empty?,
-            underline: !@node.xpath('.//w:u').empty?
-          }
-        end
-
-        def to_s
-          @text
-        end
-        
-        def italicized?
-          @formatting[:italic]
-        end
-        
-        def bolded?
-          @formatting[:bold]
-        end
-        
-        def underlined?
-          @formatting[:underline]
-        end
-      end
-    end
-  end
-end
+require 'docx/containers/container'
+
+module Docx
+  module Elements
+    module Containers
+      class TextRun
+        include Container
+        include Elements::Element
+
+        DEFAULT_FORMATTING = {
+          italic:    false,
+          bold:      false,
+          underline: false
+        }
+        
+        TAG = 'r'
+
+        attr_reader :text
+        attr_reader :formatting
+        
+        def initialize(node)
+          @node = node
+          @text_nodes = @node.xpath('w:t').map {|t_node| Elements::Text.new(t_node) }
+          @properties_tag = 'rPr'
+          @text       = parse_text || ''
+          @formatting = parse_formatting || DEFAULT_FORMATTING
+        end
+
+        # Set text of text run
+        def text=(content)
+          if @text_nodes.size == 1
+            @text_nodes.first.content = content
+          elsif @text_nodes.empty?
+            new_t = Elements::Text.create_within(self)
+            new_t.content = content
+          end
+        end
+
+        # Returns text contained within text run
+        def parse_text
+          @text_nodes.map(&:content).join('')
+        end
+
+        def parse_formatting
+          {
+            italic:    !@node.xpath('.//w:i').empty?,
+            bold:      !@node.xpath('.//w:b').empty?,
+            underline: !@node.xpath('.//w:u').empty?
+          }
+        end
+
+        def to_s
+          @text
+        end
+        
+        def italicized?
+          @formatting[:italic]
+        end
+        
+        def bolded?
+          @formatting[:bold]
+        end
+        
+        def underlined?
+          @formatting[:underline]
+        end
+      end
+    end
+  end
+end

lib/docx/document.rb

@@ -2,6 +2,19 @@
 require 'zip/zip'
 
 module Docx
+  # The Document class wraps around a docx file and provides methods to
+  # interface with it.
+  # 
+  #   # get a Docx::Document for a docx file in the local directory
+  #   doc = Docx::Document.open("test.docx")
+  #   
+  #   # get the text from the document
+  #   puts doc.text
+  #   
+  #   # do the same thing in a block
+  #   Docx::Document.open("test.docx") do |d|
+  #     puts d.text
+  #   end
   class Document
     delegate :paragraphs, :bookmarks, :to => :@parser
     delegate :doc, :xml, :zip, :to => :@parser
@@ -14,25 +27,28 @@ def initialize(path, &block)
       end
     end
 
+    # @param [String] path
+    # @return [Docx::Document]
     def self.open(path, &block)
       self.new(path, &block)
     end
 
+    ##
+    # +Deprecated+
+    # 
+    # Iterates over paragraphs within document
     def each_paragraph
       paragraphs.each { |p| yield(p) }
     end
 
+    # @return [String]
     def to_s
       paragraphs.map(&:to_s).join("\n")
     end
 
-    # TODO: Flesh this out to be compatible with other files
-    # TODO: Method to set flag on files that have been edited, probably by inserting something at the 
-    # end of methods that make edits?
-    def update
-      @replace["word/document.xml"] = doc.serialize :save_with => 0
-    end
-
+    # Save document to provided path
+    # call-seq:
+    #   save(arg1) => void
     def save(path)
       update
       Zip::ZipOutputStream.open(path) do |out|
@@ -50,5 +66,17 @@ def save(path)
     end
 
     alias_method :text, :to_s
+
+    private
+
+    #--
+    # TODO: Flesh this out to be compatible with other files
+    # TODO: Method to set flag on files that have been edited, probably by inserting something at the 
+    # end of methods that make edits?
+    #++
+    def update
+      @replace["word/document.xml"] = doc.serialize :save_with => 0
+    end
+
   end
 end