* lib/pp.rb, lib/prettyprint.rb: Documentation for PP and PrettyPrint

  Based on a patch by Vincent Batts [ruby-core:51253] [Bug #7656]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@39180 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 58 insertions, 33 deletions

diff --git a/lib/pp.rb b/lib/pp.rb
index 6e0c797d2e..134991bd71 100644
--- a/lib/pp.rb
+++ b/lib/pp.rb
@@ -1,7 +1,13 @@
 require 'prettyprint'
 
 module Kernel
-  # returns a pretty printed object as a string.
+  # Returns a pretty printed object as a string.
+  #
+  # In order to use this method you must first require the PP module:
+  #
+  #   require 'pp'
+  #
+  # See the PP module for more information.
   def pretty_inspect
     PP.pp(self, '')
   end
@@ -10,23 +16,23 @@ module Kernel
   # prints arguments in pretty form.
   #
   # pp returns argument(s).
-  def pp(*objs) # :doc:
+  def pp(*objs) # :nodoc:
     objs.each {|obj|
       PP.pp(obj)
     }
     objs.size <= 1 ? objs.first : objs
   end
-  module_function :pp
+  module_function :pp # :nodoc:
 end
 
-# == Pretty-printer for Ruby objects.
+# Pretty-printer for Ruby objects.
 #
-# = Which seems better?
+# == Which seems better?
 #
-# non-pretty-printed output by #p is:
+# Standard output by #p like this?
 #   #<PP:0x81fedf0 @genspace=#<Proc:0x81feda0>, @group_queue=#<PrettyPrint::GroupQueue:0x81fed3c @queue=[[#<PrettyPrint::Group:0x81fed78 @breakables=[], @depth=0, @break=false>], []]>, @buffer=[], @newline="\n", @group_stack=[#<PrettyPrint::Group:0x81fed78 @breakables=[], @depth=0, @break=false>], @buffer_width=0, @indent=0, @maxwidth=79, @output_width=2, @output=#<IO:0x8114ee4>>
 #
-# pretty-printed output by #pp is:
+# Or the pretty-printed version:
 #   #<PP:0x81fedf0
 #    @buffer=[],
 #    @buffer_width=0,
@@ -46,25 +52,27 @@ end
 #
 # I like the latter.  If you do too, this library is for you.
 #
-# = Usage
+# == Usage
 #
 #   pp(obj)             #=> obj
 #   pp(obj1, obj2, ...) #=> [obj1, obj2, ...]
 #   pp()                #=> nil
 #
-# output +obj(s)+ to +$>+ in pretty printed format.
+# Output <tt>obj(s)</tt> to <tt>$></tt> in pretty printed format.
 #
-# It returns +obj(s)+.
+# It returns <tt>obj(s)</tt>.
 #
 # = Output Customization
+#
 # To define your customized pretty printing function for your classes,
 # redefine a method #pretty_print(+pp+) in the class.
+#
 # It takes an argument +pp+ which is an instance of the class PP.
-# The method should use PP#text, PP#breakable, PP#nest, PP#group and
-# PP#pp to print the object.
+# The method should use #text, #breakable, #nest, #group and #pp to print the
+# object.
 #
 # = Author
-# Tanaka Akira <akr@m17n.org>
+# Tanaka Akira <akr@fsij.org>
 class PP < PrettyPrint
   # Outputs +obj+ to +out+ in pretty printed format of
   # +width+ columns in width.
@@ -106,6 +114,9 @@ class PP < PrettyPrint
   end
 
   module PPMethods
+
+    # Yields to a block
+    # and preserves the previous set of objects being printed.
     def guard_inspect_key
       if Thread.current[:__recursive_key__] == nil
         Thread.current[:__recursive_key__] = {}.untrust
@@ -125,14 +136,22 @@ class PP < PrettyPrint
       end
     end
 
+    # Check whether the object_id +id+ is in the current buffer of objects
+    # to be pretty printed. Used to break cycles in chains of objects to be
+    # pretty printed.
     def check_inspect_key(id)
       Thread.current[:__recursive_key__] &&
       Thread.current[:__recursive_key__][:inspect] &&
       Thread.current[:__recursive_key__][:inspect].include?(id)
     end
+
+    # Adds the object_id +id+ to the set of objects being pretty printed, so
+    # as to not repeat objects.
     def push_inspect_key(id)
       Thread.current[:__recursive_key__][:inspect][id] = true
     end
+
+    # Removes an object from the set of objects being pretty printed.
     def pop_inspect_key(id)
       Thread.current[:__recursive_key__][:inspect].delete id
     end
@@ -165,15 +184,19 @@ class PP < PrettyPrint
       group(1, '#<' + obj.class.name, '>', &block)
     end
 
+    # A mask used in formating object_id's into a hexadecimal id
     PointerMask = (1 << ([""].pack("p").size * 8)) - 1
 
     case Object.new.inspect
     when /\A\#<Object:0x([0-9a-f]+)>\z/
+      # String Formating for hexadecimal id
       PointerFormat = "%0#{$1.length}x"
     else
       PointerFormat = "%x"
     end
 
+    # A convenience method, like object_group, but also reformats the Object's
+    # object_id.
     def object_address_group(obj, &block)
       id = PointerFormat % (obj.object_id * 2 & PointerMask)
       group(1, "\#<#{obj.class}:0x#{id}", '>', &block)
@@ -225,6 +248,7 @@ class PP < PrettyPrint
       }
     end
 
+    # A present standard failsafe for pretty printing any given Object
     def pp_object(obj)
       object_address_group(obj) {
         seplist(obj.pretty_print_instance_variables, lambda { text ',' }) {|v|
@@ -240,6 +264,7 @@ class PP < PrettyPrint
       }
     end
 
+    # A pretty print for a Hash
     def pp_hash(obj)
       group(1, '{', '}') {
         seplist(obj, nil, :each_pair) {|k, v|
@@ -258,7 +283,7 @@ class PP < PrettyPrint
 
   include PPMethods
 
-  class SingleLine < PrettyPrint::SingleLine
+  class SingleLine < PrettyPrint::SingleLine # :nodoc:
     include PPMethods
   end
 
@@ -324,8 +349,8 @@ class PP < PrettyPrint
   end
 end
 
-class Array
-  def pretty_print(q)
+class Array # :nodoc:
+  def pretty_print(q) # :nodoc:
     q.group(1, '[', ']') {
       q.seplist(self) {|v|
         q.pp v
@@ -333,23 +358,23 @@ class Array
     }
   end
 
-  def pretty_print_cycle(q)
+  def pretty_print_cycle(q) # :nodoc:
     q.text(empty? ? '[]' : '[...]')
   end
 end
 
-class Hash
-  def pretty_print(q)
+class Hash # :nodoc:
+  def pretty_print(q) # :nodoc:
     q.pp_hash self
   end
 
-  def pretty_print_cycle(q)
+  def pretty_print_cycle(q) # :nodoc:
     q.text(empty? ? '{}' : '{...}')
   end
 end
 
-class << ENV
-  def pretty_print(q)
+class << ENV # :nodoc:
+  def pretty_print(q) # :nodoc:
     h = {}
     ENV.keys.sort.each {|k|
       h[k] = ENV[k]
@@ -358,8 +383,8 @@ class << ENV
   end
 end
 
-class Struct
-  def pretty_print(q)
+class Struct # :nodoc:
+  def pretty_print(q) # :nodoc:
     q.group(1, sprintf("#<struct %s", PP.mcall(self, Kernel, :class).name), '>') {
       q.seplist(PP.mcall(self, Struct, :members), lambda { q.text "," }) {|member|
         q.breakable
@@ -373,13 +398,13 @@ class Struct
     }
   end
 
-  def pretty_print_cycle(q)
+  def pretty_print_cycle(q) # :nodoc:
     q.text sprintf("#<struct %s:...>", PP.mcall(self, Kernel, :class).name)
   end
 end
 
-class Range
-  def pretty_print(q)
+class Range # :nodoc:
+  def pretty_print(q) # :nodoc:
     q.pp self.begin
     q.breakable ''
     q.text(self.exclude_end? ? '...' : '..')
@@ -388,9 +413,9 @@ class Range
   end
 end
 
-class File < IO
-  class Stat
-    def pretty_print(q)
+class File < IO # :nodoc:
+  class Stat # :nodoc:
+    def pretty_print(q) # :nodoc:
       require 'etc.so'
       q.object_group(self) {
         q.breakable
@@ -470,8 +495,8 @@ class File < IO
   end
 end
 
-class MatchData
-  def pretty_print(q)
+class MatchData # :nodoc:
+  def pretty_print(q) # :nodoc:
     nc = []
     self.regexp.named_captures.each {|name, indexes|
       indexes.each {|i| nc[i] = name }
@@ -495,7 +520,7 @@ class MatchData
   end
 end
 
-class Object < BasicObject
+class Object < BasicObject # :nodoc:
   include PP::ObjectMixin
 end