diff --git a/ext/readline/readline.c b/ext/readline/readline.c
index 65c0c41..e090fc9 100644
--- a/ext/readline/readline.c
+++ b/ext/readline/readline.c
@@ -460,6 +460,75 @@ readline_s_set_output(VALUE self, VALUE output)
  *
  * Set default if +proc+ is nil.
  *
+ * The String that is passed to the Proc depends on the
+ * Readline.completer_word_break_characters property. The default settings are
+ * that “the word under the cursor” is passed to the Proc. This is the normal
+ * behavior you would expect. So if you had input foo bar⇥ then only 'bar' would
+ * get passed to the completion Proc.
+ *
+ * Its common functionality that on a successful completion you may want to
+ * append a space character so that the user can immediately start working on
+ * their next argument. Readline has you covered. Just set
+ * Readline.completion_append_character.
+ *
+ * = Examples
+ *
+ * == Completion for a Static List
+ *   require 'readline'
+ *   
+ *   LIST = [
+ *     'search', 'download', 'open',
+ *     'help', 'history', 'quit',
+ *     'url', 'next', 'clear',
+ *     'prev', 'past'
+ *   ].sort
+ *   
+ *   comp = proc { |s| LIST.grep( /^#{Regexp.escape(s)}/ ) }
+ *   
+ *   Readline.completion_append_character = " "
+ *   Readline.completion_proc = comp
+ *   
+ *   while line = Readline.readline('> ', true)
+ *     p line
+ *   end
+ * == Completion For Directory Contents
+ *   require 'readline'
+ *   
+ *   Readline.completion_append_character = " "
+ *   Readline.completion_proc = Proc.new do |str|
+ *     Dir[str+'*'].grep( /^#{Regexp.escape(str)}/ )
+ *   end
+ *   
+ *   while line = Readline.readline('> ', true)
+ *     p line
+ *   end
+ * = Autocompelte strategies
+ *
+ * When working with auto-complete there are some strategies that work well. To
+ * get some ideas you can take a look at the
+ * completion.rb[http://svn.ruby-lang.org/repos/ruby/trunk/lib/irb/completion.rb]
+ * file for irb. The common strategy is to take a list of possible strings, and
+ * filter it down to only those strings that start with a given substring. In
+ * the above examples I used Enumeration.grep and passed in a regular
+ * expression. Because the input comes from the user its smart to escape the
+ * special regular expression characters in the input using Regexp.quote or
+ * Regexp.escape. The source code looks like this:
+ *   # Straightforward
+ *   regex = Regexp.new( '^' + Regexp.escape(str) )
+ *   
+ *   # Shortcut using Interpolation
+ *   regex = /^#{Regexp.escape(str)}/
+ * It may also be helpful to check out the abbrev library. Their description
+ * says it "Calculates the set of unique abbreviations for a given set of
+ * strings." Here is a quick example:
+ *   require 'abbrev'
+ *   %w[one two three].abbrev
+ *   
+ *   # Results in:
+ *   #    { "three"=>"three", "two"=>"two", "tw"=>"two",
+ *   #      "o"=>"one", "one"=>"one", "thre"=>"three",
+ *   #      "thr"=>"three", "th"=>"three", "on"=>"one" }
+ *
  * Raises ArgumentError exception if +proc+ does not respond to call method.
  *
  * Raises SecurityError exception if $SAFE is 4.