Mention Strict Locals in more documentation

Motivation / Background
---

Strict Locals support was introduced in [rails#45727][] and announced as part
of the [7.1 Release][]. There are several mentions across the Guides,
but support is rarely mentioned in the API documentation.

Detail
----

Mention the template short identifier (the pathname, in most cases) as
part of the `ArgumentError` message.

This commit adds two test cases to ensure support for splatting
additional arguments, and for forbidding block and positional arguments.

It also makes mention of strict locals in more places, and links to the
guides.

[rails#45727]: rails#45727
[7.1 Release]: https://edgeguides.rubyonrails.org/7_1_release_notes.html#allow-templates-to-set-strict-locals

Author: seanpdoyle

actionview/lib/action_view/base.rb

@@ -80,6 +80,23 @@ module ActionView # :nodoc:
   # This is useful in cases where you aren't sure if the local variable has been assigned. Alternatively, you could also use
   # <tt>defined? headline</tt> to first check if the variable has been assigned before using it.
   #
+  # By default, templates will accept any <tt>locals</tt> as keyword arguments. To restrict what <tt>locals</tt> a template accepts, add a <tt>locals:</tt> magic comment:
+  #
+  #   <%# locals: (headline:) %>
+  #
+  #   Headline: <%= headline %>
+  #
+  # In cases where the local variables are optional, declare the keyword argument with a default value:
+  #
+  #   <%# locals: (headline: nil) %>
+  #
+  #   <% unless headline.nil? %>
+  #   Headline: <%= headline %>
+  #   <% end %>
+  #
+  # Read more about strict locals in {Action View Overview}[https://guides.rubyonrails.org/action_view_overview.html#strict-locals]
+  # in the guides.
+  #
   # === Template caching
   #
   # By default, \Rails will compile each template to a method in order to render it. When you alter a template,
@@ -257,7 +274,8 @@ def _run(method, template, locals, buffer, add_to_stack: true, has_strict_locals
               message.
                 gsub("unknown keyword:", "unknown local:").
                 gsub("missing keyword:", "missing local:").
-                gsub("no keywords accepted", "no locals accepted")
+                gsub("no keywords accepted", "no locals accepted").
+                concat(" for #{@current_template.short_identifier}")
           )
         end
       else

actionview/lib/action_view/template.rb

@@ -148,6 +148,20 @@ class Template
     #     <p><%= alert %></p>
     #   <% end %>
     #
+    # By default, templates will accept any <tt>locals</tt> as keyword arguments
+    # and make them available to <tt>local_assigns</tt>. To restrict what
+    # <tt>local_assigns</tt> a template will accept, add a <tt>locals:</tt> magic comment:
+    #
+    #   <%# locals: (headline:, alerts: []) %>
+    #
+    #   <h1><%= headline %></h1>
+    #
+    #   <% alerts.each do |alert| %>
+    #     <p><%= alert %></p>
+    #   <% end %>
+    #
+    # Read more about strict locals in {Action View Overview}[https://guides.rubyonrails.org/action_view_overview.html#strict-locals]
+    # in the guides.
 
     eager_autoload do
       autoload :Error

actionview/test/template/template_test.rb

@@ -155,7 +155,7 @@ def test_locals_can_be_disabled
       render(foo: "bar")
     end
 
-    assert_match(/no locals accepted/, error.message)
+    assert_match(/no locals accepted for hello template/, error.message)
   end
 
   def test_locals_can_not_be_specified_with_positional_arguments
@@ -172,6 +172,25 @@ def test_locals_can_be_specified_with_splat_arguments
     assert_equal "bar", render(foo: "bar")
   end
 
+  def test_locals_can_be_specified_with_keyword_and_splat_arguments
+    @template = new_template("<%# locals: (id:, **attributes) -%>\n<%= tag.hr(id: id, **attributes) %>")
+    assert_equal '<hr id="1" class="h-1">', render(id: 1, class: "h-1")
+  end
+
+  def test_locals_cannot_be_specified_with_positional_arguments
+    @template = new_template("<%# locals: (argument = 'content') -%>\n<%= argument %>")
+    assert_raises ActionView::Template::Error, match: "`argument` set as non-keyword argument for hello template. Locals can only be set as keyword arguments." do
+      render
+    end
+  end
+
+  def test_locals_cannot_be_specified_with_block_arguments
+    @template = new_template("<%# locals: (&block) -%>\n<%= tag.div(&block) %>")
+    assert_raises ActionView::Template::Error, match: "`block` set as non-keyword argument for hello template. Locals can only be set as keyword arguments." do
+      render { "content" }
+    end
+  end
+
   def test_locals_can_be_specified
     @template = new_template("<%# locals: (message:) -%>\n<%= message %>")
     assert_equal "Hello", render(message: "Hello")
@@ -188,7 +207,7 @@ def test_required_locals_can_be_specified
       render
     end
 
-    assert_match(/missing local: :message/, error.message)
+    assert_match(/missing local: :message for hello template/, error.message)
   end
 
   def test_extra_locals_raises_error
@@ -197,7 +216,7 @@ def test_extra_locals_raises_error
       render(message: "Hi", foo: "bar")
     end
 
-    assert_match(/unknown local: :foo/, error.message)
+    assert_match(/unknown local: :foo for hello template/, error.message)
   end
 
   def test_rails_injected_locals_does_not_raise_error_if_not_passed

guides/source/7_1_release_notes.md

@@ -318,12 +318,23 @@ You can also set default values for these locals:
 <%= message %>
 ```
 
+Optional keyword arguments can be splatted:
+
+```erb
+<%# locals: (message: "Hello, world!", **attributes) -%>
+<%= tag.p(message, **attributes) %>
+```
+
 If you want to disable the use of locals entirely, you can do so like this:
 
 ```erb
 <%# locals: () %>
 ```
 
+Action View will process the `locals:` magic comment in any templating engine that supports `#`-prefixed comments, and will read the magic comment from any line in the partial.
+
+CAUTION: Only keyword arguments are supported. Defining positional or block arguments will raise an Action View Error at render-time.
+
 ### Add `Rails.application.deprecators`
 
 The new [`Rails.application.deprecators` method](https://github.com/rails/rails/pull/46049) returns a

guides/source/action_view_overview.md

@@ -346,6 +346,8 @@ Combining Ruby 3.1's pattern matching assignment with calls to [Hash#with_defaul
 <% end %>
 ```
 
+INFO: By default, partials will accept any `locals` as keyword arguments. To define what `locals` a partial accepts, use a `locals:` magic comment. To learn more, read about [Strict Locals](#strict-locals).
+
 [local_assigns]: https://api.rubyonrails.org/classes/ActionView/Template.html#method-i-local_assigns
 
 ### `render` without `partial` and `locals` Options
@@ -445,26 +447,73 @@ Rails will render the `_product_ruler` partial (with no data passed to it) betwe
 
 ### Strict Locals
 
-By default, templates will accept any `locals` as keyword arguments. To define what `locals` a template accepts, add a `locals` magic comment:
+By default, templates will accept any `locals` as keyword arguments. To define what `locals` a template accepts, add a `locals:` magic comment:
 
 ```erb
+<%# app/views/messages/_message.html.erb %>
+
 <%# locals: (message:) -%>
 <%= message %>
 ```
 
+Rendering the partial without a `:message` local variable argument will raise an exception:
+
+```ruby
+render "messages/message"
+# => ActionView::Template::Error: missing local: :message for app/views/messages/_message.html.erb
+```
+
 Default values can also be provided:
 
 ```erb
+<%# app/views/messages/_message.html.erb %>
+
 <%# locals: (message: "Hello, world!") -%>
 <%= message %>
 ```
 
+Rendering the partial without a `:message` local variable uses the provided default value:
+
+```ruby
+render "messages/message"
+# => "Hello, world!"
+```
+
+Rendering the partial with additional local variable arguments will raise an exception:
+
+```ruby
+render "messages/message", unknown_local: "will raise"
+# => ActionView::Template::Error: missing local: :unknown_local for app/views/messages/_message.html.erb
+```
+
+Optional local variable arguments can be splatted:
+
+```erb
+<%# app/views/messages/_message.html.erb %>
+
+<%# locals: (message: "Hello, world!", **attributes) -%>
+<%= tag.p(message, **attributes) %>
+```
+
 Or `locals` can be disabled entirely:
 
 ```erb
+<%# app/views/messages/_message.html.erb %>
+
 <%# locals: () %>
 ```
 
+Rendering the partial with any local variable arguments will raise an exception:
+
+```ruby
+render "messages/message", unknown_local: "will raise"
+# => ActionView::Template::Error: no locals accepted for app/views/messages/_message.html.erb
+```
+
+Action View will process the `locals:` magic comment in any templating engine that supports `#`-prefixed comments, and will read the magic comment from any line in the partial.
+
+CAUTION: Only keyword arguments are supported. Defining positional or block arguments will raise an Action View Error at render-time.
+
 Layouts
 -------