2 files changed, 44 insertions, 7 deletions
diff --git a/lib/psych.rb b/lib/psych.rb
index 848a71d..02925be 100644
--- a/lib/psych.rb
+++ b/lib/psych.rb
@@ -19,13 +19,16 @@ require 'psych/set'
 require 'psych/psych'
 
 ###
-# Psych is a YAML parser and emitter.
+# Psych is a YAML parser and emitter.  Psych leverages
+# libyaml[http://libyaml.org] for it's YAML parsing and emitting capabilities.
+# In addition to wrapping libyaml, Psych also knows how to serialize and
+# de-serialize most Ruby objects to and from the YAML format.
 #
 # == YAML Parsing
 #
 # Psych provides a range of interfaces for parsing a YAML document ranging from
 # low level to high level, depending on your parsing needs.  At the lowest
-# level, is an event based parser.  Mid-level is access to the raw YAML AST,
+# level, is an event based parser.  Mid level is access to the raw YAML AST,
 # and at the highest level is the ability to unmarshal YAML to ruby objects.
 #
 # === Low level parsing
diff --git a/lib/psych/parser.rb b/lib/psych/parser.rb
index a59c435..caa544c 100644
--- a/lib/psych/parser.rb
+++ b/lib/psych/parser.rb
@@ -1,19 +1,53 @@
 module Psych
   ###
-  # YAML parser class.
+  # YAML event parser class.  This class parses a YAML document and calls
+  # events on the handler that is passed to the constructor.  The events can
+  # be used for things such as constructing a YAML AST or deserializing YAML
+  # documents.  It can even be fed back to Psych::Emitter to emit the same
+  # document that was parsed.
   #
-  # Example:
+  # See Psych::Handler for documentation on the events that Psych::Parser emits.
   #
-  #   parser = Psych::Parser.new
-  #   parser.parse(some_yaml)
+  # Here is an example that prints out ever scalar found in a YAML document:
+  #
+  #   # Handler for detecting scalar values
+  #   class ScalarHandler < Psych::Handler
+  #     def scalar value, anchor, tag, plain, quoted, style
+  #       puts value
+  #     end
+  #   end
+  #
+  #   parser = Psych::Parser.new(ScalarHandler.new)
+  #   parser.parse(yaml_document)
+  #
+  # Here is an example that feeds the parser back in to Psych::Emitter.  The
+  # YAML document is read from STDIN and written back out to STDERR:
+  #
+  #   parser = Psych::Parser.new(Psych::Emitter.new($stderr))
+  #   parser.parse($stdin)
+  #
+  # Psych uses Psych::Parser in combination with Psych::TreeBuilder to
+  # construct an AST of the parsed YAML document.
+
   class Parser
+    # The handler on which events will be called
     attr_accessor :handler
 
+    ###
+    # Creates a new Psych::Parser instance with +handler+.  YAML events will
+    # be called on +handler+.  See Psych::Parser for more details.
+
     def initialize handler = Handler.new
       @handler = handler
     end
 
-    def parse string
+    ###
+    # Parse the YAML document contained in +yaml+.  Events will be called on
+    # the handler set on the parser instance.
+    #
+    # See Psych::Parser and Psych::Parser#handler
+
+    def parse yaml
       parse_string string
     end
   end