Refine documentation examples

Fix minor wording issues, document print_tree output helpers in README, and
clarify cmp policy coverage in History.

Author: evolve75

History.md

@@ -13,7 +13,8 @@
 * Cycle prevention in `add` eliminates the earlier `to_s`/`size` infinite-loop
   risk caused by cyclic graphs.
 
-* Add `cmp` for traversal/relationship-based comparison without changing the
+* Add `cmp` for traversal/relationship-based comparisons (`:each`,
+  `:breadth_each`, `:direct_or_sibling`, `:direct_only`) without changing the
   name-based `<=>` semantics.
 
 * Allow `print_tree` to write to a custom IO and add `print_tree_to_s` for

README.md

@@ -77,6 +77,7 @@ See the [API][rt_doc] documentation for more details.
 
 # ..... Example starts.
 require 'tree'                 # Load the library
+require 'stringio'
 
 # ..... Create the root node first.
 # ..... Note that every node has a name and an optional content payload.
@@ -92,8 +93,13 @@ root_node << Tree::TreeNode.new("CHILD2", "Child2 Content")
 # ..... This is primarily used for debugging purposes.
 root_node.print_tree
 
+# ..... You can capture the output or request a formatted string.
+buffer = StringIO.new
+root_node.print_tree(io: buffer)
+output = root_node.print_tree_to_s
+
 # ..... Lets directly access children and grandchildren of the root.
-# ..... The can be "chained" for a given path to any depth.
+# ..... These can be "chained" for a given path to any depth.
 child1       = root_node["CHILD1"]
 grand_child1 = root_node["CHILD1"]["GRANDCHILD1"]
 
@@ -136,6 +142,10 @@ This example can also be found at
     * [RSpec][] for additional Ruby Spec test files
     * [RuboCop][] for linting the code
 
+Note: `Tree::TreeNode.new` accepts `{ checks: false }` to disable validation
+guards in performance-critical code paths. This is risky and should only be
+used when benchmark data clearly justifies the risk.
+
 ## INSTALL: ##
 
 To install the [gem][rt_gem], run this command from a terminal/shell:

Rakefile

@@ -68,7 +68,7 @@ namespace :doc do # ................................ Documentation
     require 'rdoc/task'
     Rake::RDocTask.new do |rdoc|
       rdoc.rdoc_dir = 'rdoc'
-      rdoc.title    = "RubyTree Documenation: #{PKG_NAME}-#{PKG_VER}"
+      rdoc.title    = "RubyTree Documentation: #{PKG_NAME}-#{PKG_VER}"
       rdoc.main     = 'README.md'
       rdoc.rdoc_files.include(GEM_SPEC.extra_rdoc_files)
       rdoc.rdoc_files.include('./lib/**/*.rb')

lib/tree.rb

@@ -53,7 +53,7 @@ module Tree
   # == TreeNode Class Description
   #
   # This class models the nodes for an *N-ary* tree data structure. The
-  # nodes are *named*, and have a place-holder for the node data (i.e.,
+  # nodes are *named*, and have a placeholder for the node data (i.e.,
   # _content_ of the node). The node names are required to be *unique*
   # amongst the sibling/peer nodes. Note that the name is implicitly
   # used as an _ID_ within the data structure).

lib/tree/utils/json_converter.rb

@@ -77,7 +77,7 @@ def as_json(_options = {})
         json_hash
       end
 
-      # Creates a JSON representation of this node including all it's children.
+      # Creates a JSON representation of this node including all its children.
       # This requires the JSON gem to be available, or else the operation fails with
       # a warning message.  Uses the Hash output of #as_json method.
       #