param_matchers.rb in roda-3.3.0

- old
+ new
@@ -7,35 +7,42 @@
     # on the request's params.
     #
     # It adds a :param matcher for matching on any param with the
     # same name, yielding the value of the param:
     #
-    #   r.on param: 'foo' do |value|
+    #   r.on param: 'foo' do |foo|
     #     # Matches '?foo=bar', '?foo='
     #     # Doesn't match '?bar=foo'
     #   end
     #
     # It adds a :param! matcher for matching on any non-empty param
     # with the same name, yielding the value of the param:
     #
-    #   r.on(param!: 'foo') do |value|
+    #   r.on(param!: 'foo') do |foo|
     #     # Matches '?foo=bar'
     #     # Doesn't match '?foo=', '?bar=foo'
     #   end
     #
     # It also adds :params and :params! matchers, for matching multiple
     # params at the same time:
     #
-    #   r.on params: ['foo', 'baz'] do |value|
+    #   r.on params: ['foo', 'baz'] do |foo, baz|
     #     # Matches '?foo=bar&baz=quuz', '?foo=&baz='
     #     # Doesn't match '?foo=bar', '?baz='
     #   end
     #
-    #   r.on params!: ['foo', 'baz'] do |value|
+    #   r.on params!: ['foo', 'baz'] do |foo, baz|
     #     # Matches '?foo=bar&baz=quuz'
     #     # Doesn't match '?foo=bar', '?baz=', '?foo=&baz=', '?foo=bar&baz='
     #   end
     #
+    # Because users have some control over the types of submitted parameters,
+    # it is recommended that you explicitly force the correct type for values
+    # yielded by the block:
+    #
+    #   r.get(:param=>'foo') do |foo|
+    #     foo = foo.to_s
+    #   end
     module ParamMatchers
       module RequestMethods
         # Match the given parameter if present, even if the parameter is empty.
         # Adds match to the captures.
         def match_param(key)