Additional file patterns docs (#637)

Add better documentation for new option for additional file patterns. Implemented in #633 and #636.

README.rdoc

@@ -163,7 +163,7 @@ you can do so with a simple environment variable, instead of editing the
 == Options
 
     Usage: annotate [options] [model_file]*
-            --additional_file_patterns      Additional file paths or globs to annotate
+            --additional_file_patterns   Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)
         -d, --delete                     Remove annotations from all model files or the routes.rb file
         -p [before|top|after|bottom],    Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/route/serializer file(s)
             --position
@@ -206,15 +206,35 @@ you can do so with a simple environment variable, instead of editing the
             --frozen                     Do not allow to change annotations. Exits non-zero if there are going to be changes to files.
             --timestamp                  Include timestamp in (routes) annotation
             --trace                      If unable to annotate a file, print the full stack trace, not just the exception message.
-        -I, --ignore-columns REGEX       don't annotate columns that match a given REGEX (i.e., `annotate -I '^(id|updated_at|created_at)'`
-            --ignore-routes REGEX        don't annotate routes that match a given REGEX (i.e., `annotate -I '(mobile|resque|pghero)'`
+        -I, --ignore-columns REGEX       don't annotate columns that match a given REGEX (e.g. `annotate -I '^(id|updated_at|created_at)'`)
+            --ignore-routes REGEX        don't annotate routes that match a given REGEX (e.g. `annotate -I '(mobile|resque|pghero)'`)_
             --hide-limit-column-types VALUES
-                                         don't show limit for given column types, separated by commas (i.e., `integer,boolean,text`)
+                                         don't show limit for given column types, separated by commas (e.g. `integer,boolean,text`)
             --hide-default-column-types VALUES
-                                         don't show default for given column types, separated by commas (i.e., `json,jsonb,hstore`)
+                                         don't show default for given column types, separated by commas (e.g. `json,jsonb,hstore`)
             --ignore-unknown-models      don't display warnings for bad model files
             --with-comment               include database comments in model annotations
 
+=== Option: +additional_file_patterns+
+
+CLI: +--additional_file_patterns+<br>
+Ruby: +:additional_file_patterns+
+
+Provide additional paths for the gem to annotate.  These paths can include globs.
+It is recommended to use absolute paths.  Here are some examples:
+
+
+- <code>/app/lib/decorates/%MODEL_NAME%/&ast;.rb</code>
+- <code>/app/lib/forms/%PLURALIZED_MODEL_NAME%/&ast;&ast;/&ast;.rb</code>
+- <code>/app/lib/forms/%TABLE_NAME%/&ast;.rb</code>
+
+The appropriate model will be inferred using the <code>%*%</code> syntax, annotating any matching files.
+It works with existing filename resolutions (options for which can be found in the +resolve_filename+ method of
++annotate_models.rb+).
+
+When using in a Rails config, you can use the following:
+
+<code>File.join(Rails.application.root, 'app/lib/forms/%PLURALIZED_MODEL_NAME%/**/*.rb')</code>
 
 == Sorting
 

lib/annotate/parser.rb

@@ -49,7 +49,7 @@ def add_options_to_parser(option_parser) # rubocop:disable Metrics/MethodLength
 
       option_parser.banner = 'Usage: annotate [options] [model_file]*'
 
-      option_parser.on('--additional_file_patterns path1,path2,path3', Array, "Additional file paths or globs to annotate") do |additional_file_patterns|
+      option_parser.on('--additional_file_patterns path1,path2,path3', Array, "Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)") do |additional_file_patterns|
         ENV['additional_file_patterns'] = additional_file_patterns
       end