2 files changed, 63 insertions, 1 deletions

diff --git a/README.rdoc b/README.rdoc
index 66d8d99..f94c287 100644
--- a/README.rdoc
+++ b/README.rdoc
@@ -4,7 +4,9 @@
 
 == Description
 
-Wrapper around libyaml that provides the same interface as Syck
+Psych is a YAML parser that wraps libyaml.  Psych provides a similar ruby
+interface for parsing and emitting that Syck does, but uses libyaml for the
+heavy lifting.
 
 == Examples
 
diff --git a/lib/psych.rb b/lib/psych.rb
index 4327637..ed7af3c 100644
--- a/lib/psych.rb
+++ b/lib/psych.rb
@@ -18,6 +18,66 @@ require 'psych/omap'
 require 'psych/set'
 require 'psych/psych'
 
+###
+# Psych is a YAML parser and emitter.
+#
+# == 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,
+# and at the highest level is the ability to unmarshal YAML to ruby objects.
+#
+# === Low level parsing
+#
+# The lowest level parser should be used when the YAML input is already known,
+# and the developer does not want to pay the price of building an AST or
+# automatic detection and conversion to ruby objects.  See Psych::Parser for
+# more information on using the event based parser.
+#
+# === Mid level parsing
+#
+# Psych provides access to an AST produced from parsing a YAML document.  This
+# tree is built using the Psych::Parser and Psych::TreeBuilder.  The AST can
+# be examined and manipulated freely.  Please see Psych::yaml_ast,
+# Psych::Nodes, and Psych::Nodes::Node for more information on dealing with
+# YAML syntax trees.
+#
+# === High level parsing
+#
+# The high level YAML parser provided by Psych simply takes YAML as input and
+# returns a Ruby data structure.  For information on using the high level parser
+# see Psych.load
+#
+# == YAML Emitting
+#
+# Psych provides a range of interfaces ranging from low to high level for
+# producing YAML documents.  Very similar to the YAML parsing interfaces, Psych
+# provides at the lowest level, an event based system, mid-level is building
+# a YAML AST, and the highest level is converting a Ruby object straight to
+# a YAML document.
+#
+# === Low level emitting
+#
+# The lowest level emitter is an event based system.  Events are sent to a
+# Psych::Emitter object.  That object knows how to convert the events to a YAML
+# document.  This interface should be used when document format is known in
+# advance or speed is a concern.  See Psych::Emitter for more information.
+#
+# === Mid level emitting
+#
+# At the mid level is building an AST.  This AST is exactly the same as the AST
+# used when parsing a YAML document.  Users can build an AST by hand and the
+# AST knows how to emit itself as a YAML document.  See Psych::Nodes,
+# Psych::Nodes::Node, and Psych::TreeBuilder for more information on building
+# a YAML AST.
+#
+# === High level emitting
+#
+# The high level emitter has the easiest interface.  Psych simply takes a Ruby
+# data structure and converts it to a YAML document.  See Psych.dump for more
+# information on dumping a Ruby data structure.
+
 module Psych
   VERSION         = '1.0.0'
   LIBYAML_VERSION = Psych.libyaml_version.join '.'