+ documentation cleanup

Rakefile

@@ -64,6 +64,8 @@ require 'sdoc'
 
 # Generate documentation
 Rake::RDocTask.new do |rdoc|
+  rdoc.title    = "parslet - construction of parsers made easy"
+  rdoc.options << '--line-numbers' << '--inline-source'
   rdoc.options << '--fmt' << 'shtml' # explictly set shtml generator
   rdoc.template = 'direct' # lighter template used on railsapi.com
   rdoc.main = "README"

lib/parslet.rb

@@ -21,8 +21,10 @@
 # Parslet is typically used in stages: 
 #
 # 
-# * Parsing the input string; this yields an intermediary tree
-# * Transformation of the tree into something useful to you
+# * Parsing the input string; this yields an intermediary tree, see Parslet.any, Parslet.match, 
+#   Parslet.str, Parslet::ClassMethods#rule and Parslet::ClassMethods#root.
+# * Transformation of the tree into something useful to you, see Parslet::Transform, 
+#   Parslet.simple, Parslet.sequence and Parslet.subtree.
 #
 # The first stage is traditionally intermingled with the second stage; output
 # from the second stage is usually called the 'Abstract Syntax Tree' or AST. 
@@ -31,6 +33,12 @@
 # and use the second stage to isolate the rest of your code from the changes
 # you've effected. 
 #
+# == When things go wrong
+#
+# A parse that fails will raise Parslet::ParseFailed. A detailed explanation
+# of what went wrong can be obtained from the parslet involved or the root
+# of the parser instance. 
+#
 module Parslet
   def self.included(base)
     base.extend(ClassMethods)
@@ -47,7 +55,7 @@ def self.included(base)
   #   begin
   #     parslet.parse(str)
   #   rescue Parslet::ParseFailed => failure
-  #     puts parslet.error_tree.ascii_tree
+  #     puts parslet.error_tree
   #   end
   #
   class ParseFailed < Exception
@@ -96,9 +104,7 @@ def root(name)
     #       bar >> bar
     #     end
     #
-    #     def parse(str)
-    #       twobar.parse(str)
-    #     end
+    #     root :twobar
     #   end
     #
     def rule(name, &definition)
@@ -109,23 +115,28 @@ def rule(name, &definition)
       end
     end
   end
-  
-  # Allows for delayed construction of #match.
+
+  # Allows for delayed construction of #match. See also Parslet.match.
   #
-  class DelayedMatchConstructor
+  class DelayedMatchConstructor #:nodoc:
     def [](str)
       Atoms::Re.new("[" + str + "]")
     end
   end
 
-  # Returns an atom matching a character class. This is essentially a regular
-  # expression, but you should only match a single character. 
+  # Returns an atom matching a character class. All regular expressions can be
+  # used, as long as they match only a single character at a time. 
   #
   # Example: 
   #
   #   match('[ab]')     # will match either 'a' or 'b'
   #   match('[\n\s]')   # will match newlines and spaces
   #
+  # There is also another (convenience) form of this method: 
+  #
+  #   match['a-z']      # synonymous to match('[a-z]')
+  #   match['\n']       # synonymous to match('[\n]')
+  #
   def match(str=nil)
     return DelayedMatchConstructor.new unless str
 
@@ -158,7 +169,7 @@ def any
   #
   #   exp(%Q("a" "b"?))     # => returns the same as str('a') >> str('b').maybe
   #
-  def exp(str)
+  def exp(str) # :nodoc:
     Parslet::Expression.new(str).to_parslet
   end
   module_function :exp

lib/parslet/atoms/entity.rb

@@ -1,13 +1,12 @@
 # This wraps pieces of parslet definition and gives them a name. The wrapped
 # piece is lazily evaluated and cached. This has two purposes: 
 #     
-# a) Avoid infinite recursion during evaluation of the definition
-#
-# b) Be able to print things by their name, not by their sometimes
-#    complicated content.
+# * Avoid infinite recursion during evaluation of the definition
+# * Be able to print things by their name, not by their sometimes
+#   complicated content.
 #
 # You don't normally use this directly, instead you should generated it by
-# using the structuring method Parslet#rule.
+# using the structuring method Parslet.rule.
 #
 class Parslet::Atoms::Entity < Parslet::Atoms::Base
   attr_reader :name, :context, :block

lib/parslet/expression/treetop.rb

@@ -1,5 +1,5 @@
 class Parslet::Expression::Treetop
-  class Parser < Parslet::Parser
+  class Parser < Parslet::Parser # :nodoc:
     root(:expression)
 
     rule(:expression) { alternatives }
@@ -39,7 +39,7 @@ def spaced(str)
     end
   end
 
-  class Transform < Parser::Transform
+  class Transform < Parser::Transform # :nodoc:
     rule(:alt => subtree(:alt)) { Parslet::Atoms::Alternative.new(*alt) }
     rule(:seq => sequence(:s))  { Parslet::Atoms::Sequence.new(*s) }
     rule(:unwrap => simple(:u)) { u }

lib/parslet/transform.rb

@@ -46,10 +46,13 @@
 # tree that looks like this: 
 #
 #   {
-#     :l => "(", 
-#     :m => {
-#       :l=>"(", :m=>nil, :r=>")" }, 
-#     :r => ")"
+#     l: '(', 
+#     m: {
+#       l: '(', 
+#       m: nil, 
+#       r: ')' 
+#     }, 
+#     r: ')' 
 #   }
 #
 # This parse tree is good for debugging, but what we would really like to have
@@ -100,26 +103,36 @@ def rule(expression, &block)
 
     # Allows accessing the class' rules
     #
-    def rules
+    def rules # :nodoc: 
       @__transform_rules || []
     end
   end
 
-  def initialize(&block)
+  def initialize(&block) # :nodoc: 
     @rules = []
 
     if block
       instance_eval(&block)
     end
   end
 
+  # Defines a rule to be applied whenever apply is called on a tree. A rule
+  # is composed of two parts: 
+  # 
+  # * an *expression pattern*
+  # * a *transformation block*
+  #
   def rule(expression, &block)
     @rules << [
       Parslet::Pattern.new(expression), 
       block
     ]
   end
 
+  # Applies the transformation to a tree that is generated by Parslet::Parser
+  # or a simple parslet. Transformation will proceed down the tree, replacing
+  # parts/all of it with new objects. The resulting object will be returned. 
+  #
   def apply(obj)
     transform_elt(
       case obj
@@ -136,11 +149,11 @@ def apply(obj)
   # Allow easy access to all rules, the ones defined in the instance and the 
   # ones predefined in a subclass definition. 
   #
-  def rules
+  def rules # :nodoc: 
     self.class.rules + @rules
   end
 
-  def transform_elt(elt)
+  def transform_elt(elt) # :nodoc: 
     rules.each do |pattern, block|
       if bindings=pattern.match(elt)
         # Produces transformed value
@@ -151,13 +164,13 @@ def transform_elt(elt)
     # No rule matched - element is not transformed
     return elt
   end
-  def recurse_hash(hsh)
+  def recurse_hash(hsh) # :nodoc: 
     hsh.inject({}) do |new_hsh, (k,v)|
       new_hsh[k] = apply(v)
       new_hsh
     end
   end
-  def recurse_array(ary)
+  def recurse_array(ary) # :nodoc: 
     ary.map { |elt| apply(elt) }
   end
 end