Merge pull request #33810 from schneems/schneems/doc-output-buffer

Document ActionView::OutputBuffer

2 files changed, 19 insertions, 0 deletions

diff --git a/actionview/lib/action_view/buffers.rb b/actionview/lib/action_view/buffers.rb
index 2a378fdc3c..18eaee5d79 100644
--- a/actionview/lib/action_view/buffers.rb
+++ b/actionview/lib/action_view/buffers.rb
@@ -3,6 +3,21 @@
 require "active_support/core_ext/string/output_safety"
 
 module ActionView
+  # Used as a buffer for views
+  #
+  # The main difference between this and ActiveSupport::SafeBuffer
+  # is for the methods `<<` and `safe_expr_append=` the inputs are
+  # checked for nil before they are assigned and `to_s` is called on
+  # the input. For example:
+  #
+  #   obuf = ActionView::OutputBuffer.new "hello"
+  #   obuf << 5
+  #   puts obuf # => "hello5"
+  #
+  #   sbuf = ActiveSupport::SafeBuffer.new "hello"
+  #   sbuf << 5
+  #   puts sbuf # => "hello\u0005"
+  #
   class OutputBuffer < ActiveSupport::SafeBuffer #:nodoc:
     def initialize(*)
       super
diff --git a/actionview/lib/action_view/helpers/capture_helper.rb b/actionview/lib/action_view/helpers/capture_helper.rb
index 92f7ddb70d..c87c212cc7 100644
--- a/actionview/lib/action_view/helpers/capture_helper.rb
+++ b/actionview/lib/action_view/helpers/capture_helper.rb
@@ -36,6 +36,10 @@ module ActionView
       #   </body>
       #   </html>
       #
+      # The return of capture is the string generated by the block. For Example:
+      #
+      #   @greeting # => "Welcome to my shiny new web page! The date and time is 2018-09-06 11:09:16 -0500"
+      #
       def capture(*args)
         value = nil
         buffer = with_output_buffer { value = yield(*args) }