More documentation, better examples in Readme

Author: chrahunt

README.md

@@ -1,69 +1,77 @@
-# docx
-
-a ruby library/gem for interacting with `.docx` files. currently capabilities include reading paragraphs/bookmarks, inserting text at bookmarks, and saving the document.
-
-## usage
-
-### install
-
-requires ruby (only tested with 1.9.3 so far)
-
-    gem install docx
-
-### reading
-
-``` ruby
-require 'docx'
-
-d = Docx::Document.open('example.docx')
-# Array of paragraphs
-d.paragraphs.each do |p|
-  puts d
-end
-
-# Hash of Bookmarks. Bookmark names as keys correspond to bookmark objects.
-d.bookmarks.each_pair do |bookmark_name, bookmark_object|
-  puts bookmark_name
-end
-```
-
-### writing
-
-``` ruby
-require 'docx'
-
-d = Docx::Document.open('example.docx')
-# Insert a single line after a bookmark
-d.bookmarks['example_bookmark'].insert_after("Hello world.")
-# Each value in array is put on a separate line
-d.bookmarks['example_bookmark'].insert_multiple_lines_after(['Hello', 'World', 'foo'])
-```
-
-### advanced
-
-``` ruby
-require 'docx'
-
-d = Docx::Document.open('example.docx')
-
-# The Nokogiri node on which an element is based can be accessed using #node
-d.paragraphs.each do |p|
-  puts p.node.inspect
-end
-
-# The #xpath and #at_xpath are delegated to the node from the element, saving a step
-p_element = d.paragraphs.first
-p_children = p_element.xpath("//child::*") # selects all children
-p_child = p_element.at_xpath("//child::*") # selects first child
-```
-
-## Development
-
-### todo
-
-* Add better formatting identification for specific nodes and other formatting indicators (text size, paragraph spacing)
-* Calculate element formatting based on values present in element properties as well as properties inherited from parents
-* Default formatting of inserted elements to inherited values
-* Implement formattable elements.
-* Implement styles.
+# docx
+
+a ruby library/gem for interacting with `.docx` files. currently capabilities include reading paragraphs/bookmarks, inserting text at bookmarks, and saving the document.
+
+## usage
+
+### install
+
+requires ruby (only tested with 1.9.3 so far)
+
+    gem install docx
+
+### reading
+
+``` ruby
+require 'docx'
+
+# Create a Docx::Document object for our existing docx file
+doc = Docx::Document.open('example.docx')
+
+# Retrieve and display paragraphs
+doc.paragraphs.each do |p|
+  puts p
+end
+
+# Retrieve and display bookmarks, returned as hash with bookmark names as keys and objects as values
+doc.bookmarks.each_pair do |bookmark_name, bookmark_object|
+  puts bookmark_name
+end
+```
+
+### writing
+
+``` ruby
+require 'docx'
+
+# Create a Docx::Document object for our existing docx file
+doc = Docx::Document.open('example.docx')
+
+# Insert a single line of text after one of our bookmarks
+doc.bookmarks['example_bookmark'].insert_after("Hello world.")
+
+# Insert multiple lines of text at our bookmark
+doc.bookmarks['example_bookmark_2'].insert_multiple_lines_after(['Hello', 'World', 'foo'])
+
+# Save document to specified path
+doc.save('example-edited.docx')
+```
+
+### advanced
+
+``` ruby
+require 'docx'
+
+d = Docx::Document.open('example.docx')
+
+# The Nokogiri::XML::Node on which an element is based can be accessed using #node
+d.paragraphs.each do |p|
+  puts p.node.inspect
+end
+
+# The #xpath and #at_xpath methods are delegated to the node from the element, saving a step
+p_element = d.paragraphs.first
+p_children = p_element.xpath("//child::*") # selects all children
+p_child = p_element.at_xpath("//child::*") # selects first child
+```
+
+## Development
+
+### todo
+
+* Add better formatting identification for specific nodes and other formatting indicators (text size, paragraph spacing)
+* Calculate element formatting based on values present in element properties as well as properties inherited from parents
+* Default formatting of inserted elements to inherited values
+* Implement formattable elements.
+* Implement styles.
 * Easier multi-line text insertion at a single bookmark (inserting paragraph nodes after the one containing the bookmark)

lib/docx.rb

@@ -1,7 +1,7 @@
-require 'docx/version'
-
-module Docx
-  autoload :Document, 'docx/document'
-end
-
+require 'docx/version'
+
+module Docx #:nodoc:
+  autoload :Document, 'docx/document'
+end
+
 require 'docx/core_ext/module'

lib/docx/document.rb

@@ -27,28 +27,33 @@ def initialize(path, &block)
       end
     end
 
-    # @param [String] path
-    # @return [Docx::Document]
+    # With no associated block, Docx::Document.open is a synonym for Docx::Document.new. If the optional code block is given, it will be passed the opened +docx+ file as an argument and the Docx::Document oject will automatically be closed when the block terminates. The values of the block will be returned from Docx::Document.open.
+    # call-seq:
+    #   open(filepath) => file
+    #   open(filepath) {|file| block } => obj
     def self.open(path, &block)
       self.new(path, &block)
     end
 
     ##
-    # +Deprecated+
+    # *Deprecated*
     # 
     # Iterates over paragraphs within document
+    # call-seq:
+    #   each_paragraph => Enumerator
     def each_paragraph
       paragraphs.each { |p| yield(p) }
     end
 
-    # @return [String]
+    # call-seq:
+    #   to_s -> string
     def to_s
       paragraphs.map(&:to_s).join("\n")
     end
 
     # Save document to provided path
     # call-seq:
-    #   save(arg1) => void
+    #   save(filepath) => void
     def save(path)
       update
       Zip::ZipOutputStream.open(path) do |out|

lib/docx/elements/bookmark.rb

@@ -13,19 +13,19 @@ def initialize(node)
         @name = @node['w:name']
       end
 
-      # Insert text before bookmark node
+      # Insert text before bookmarkStart node
       def insert_text_before(text)
         text_run = get_run_after
         text_run.text = "#{text}#{text_run.text}"
       end
 
-      # Insert text after bookmark node
+      # Insert text after bookmarkStart node
       def insert_text_after(text)
         text_run = get_run_before
         text_run.text = "#{text_run.text}#{text}"
       end
 
-      # Insert multiple lines adjacent to bookmark node
+      # insert multiple lines starting with paragraph containing bookmark node.
       def insert_multiple_lines(text_array)
         # Hold paragraphs to be inserted into, corresponding to the index of the strings in the text array
         paragraphs = []

lib/docx/parser.rb

@@ -33,10 +33,12 @@ def bookmarks
 
     private
 
+    # generate Elements::Containers::Paragraph from paragraph XML node
     def parse_paragraph_from(p_node)
       Elements::Containers::Paragraph.new(p_node)
     end
 
+    # generate Elements::Bookmark from bookmark XML node
     def parse_bookmark_from(b_node)
       Elements::Bookmark.new(b_node)
     end