diff --git a/ChangeLog b/ChangeLog
index bb16495668..53d9a7324b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+Sat Dec 23 01:35:00 2012  Zachary Scott  <zachary@zacharyscott.net>
+
+	* lib/optparse.rb: Documentation for OptionParser to remove 'shadowed
+	  outer local variable' from example and make obvious ARGV with
+	  non-option arguments.
+	  Patch by Marcus Stollsteimer [ruby-core:47460] [Bug #6997]
+
 Sat Dec 23 00:08:00 2012  Kenta Murata  <mrkn@mrkn.jp>
 
 	* include/ruby/intern.h: add the prototype declaration of
diff --git a/lib/optparse.rb b/lib/optparse.rb
index 9648f75fd2..469fde29ae 100644
--- a/lib/optparse.rb
+++ b/lib/optparse.rb
@@ -111,7 +111,7 @@
 #       options.transfer_type = :auto
 #       options.verbose = false
 #
-#       opts = OptionParser.new do |opts|
+#       opt_parser = OptionParser.new do |opts|
 #         opts.banner = "Usage: example.rb [options]"
 #
 #         opts.separator ""
@@ -190,7 +190,7 @@
 #         end
 #       end
 #
-#       opts.parse!(args)
+#       opt_parser.parse!(args)
 #       options
 #     end  # parse()
 #
@@ -198,6 +198,7 @@
 #
 #   options = OptparseExample.parse(ARGV)
 #   pp options
+#   pp ARGV
 #
 # === Shell Completion
 #
@@ -1338,6 +1339,7 @@ XXX
 
   #
   # Same as #order, but removes switches destructively.
+  # Non-option arguments remain in +argv+.
   #
   def order!(argv = default_argv, &nonopt)
     parse_in_order(argv, &nonopt)
@@ -1428,6 +1430,7 @@ XXX
 
   #
   # Same as #permute, but removes switches destructively.
+  # Non-option arguments remain in +argv+.
   #
   def permute!(argv = default_argv)
     nonopts = []
@@ -1447,6 +1450,7 @@ XXX
 
   #
   # Same as #parse, but removes switches destructively.
+  # Non-option arguments remain in +argv+.
   #
   def parse!(argv = default_argv)
     if ENV.include?('POSIXLY_CORRECT')