Add an example for #stop_on_unknown_option!

lib/thor.rb

@@ -258,6 +258,35 @@ def check_unknown_options?(config) #:nodoc:
     # options, and where those additional options should not be handled by
     # Thor.
     #
+    # ==== Example
+    #
+    # To better understand how this is useful, let's consider a task that calls
+    # an external command.  A user may want to pass arbitrary options and
+    # arguments to that command.  The task itself also accepts some options,
+    # which should be handled by Thor.
+    #
+    #   class_option "verbose",  :type => :boolean
+    #   stop_on_unknown_option! :exec
+    #   check_unknown_options!  :except => :exec
+    #
+    #   desc "exec", "Run a shell command"
+    #   def exec(*args)
+    #     puts "diagnostic output" if options[:verbose]
+    #     Kernel.exec(*args)
+    #   end
+    #
+    # Here +exec+ can be called with +--verbose+ to get diagnostic output,
+    # e.g.:
+    #
+    #   $ thor exec --verbose echo foo
+    #   diagnostic output
+    #   foo
+    #
+    # But if +--verbose+ is given after +echo+, it is passed to +echo+ instead:
+    #
+    #   $ thor exec echo --verbose foo
+    #   --verbose foo
+    #
     # ==== Parameters
     # Symbol ...:: A list of tasks that should be affected.
     def stop_on_unknown_option!(*task_names)