From faf208ad659ed6fe99bb8cc081e3e855b7575378 Mon Sep 17 00:00:00 2001
From: Shaina Raskas <shaina.raskas@shopify.com>
Date: Mon, 14 Mar 2022 23:06:01 +0000
Subject: [PATCH] some tags

---
 lib/liquid/block_body.rb   | 12 ++++++++++++
 lib/liquid/tags/comment.rb | 14 +++++++++++++-
 lib/liquid/tags/echo.rb    | 20 ++++++++++----------
 lib/liquid/tags/raw.rb     | 10 ++++++++++
 lib/liquid/tags/render.rb  | 23 +++++++++++++++++++++++
 5 files changed, 68 insertions(+), 11 deletions(-)

diff --git a/lib/liquid/block_body.rb b/lib/liquid/block_body.rb
index 2921ce88..d3765d49 100644
--- a/lib/liquid/block_body.rb
+++ b/lib/liquid/block_body.rb
@@ -35,6 +35,18 @@ module Liquid
       super
     end
 
+    # @public_docs
+    # @type tag
+    # @category theme
+    # @title liquid
+    # @summary
+    #   Allows you to write multiple tags within one set of delimiters.
+    # @description
+    #   Use the [`echo`](/api/liquid/tags/theme-tags#echo) tag to output an expression within a `liquid` tag.
+    # @syntax
+    #   {% liquid
+    #     statement
+    #   %}
     private def parse_for_liquid_tag(tokenizer, parse_context)
       while (token = tokenizer.shift)
         unless token.empty? || token =~ WhitespaceOrNothing
diff --git a/lib/liquid/tags/comment.rb b/lib/liquid/tags/comment.rb
index a5460f99..f9e05ae0 100644
--- a/lib/liquid/tags/comment.rb
+++ b/lib/liquid/tags/comment.rb
@@ -1,6 +1,18 @@
 # frozen_string_literal: true
-
 module Liquid
+
+  # @public_docs
+  # @type tag
+  # @category theme
+  # @title comment
+  # @summary
+  #   Allows you to comment out parts of a Liquid file.
+  #   Any text within the opening and closing `comment` blocks won't be output,
+  #   and any Liquid code won't be executed.
+  # @syntax
+  #   {% comment %}
+  #     statement
+  #   {% endcomment %}
   class Comment < Block
     def render_to_output_buffer(_context, output)
       output
diff --git a/lib/liquid/tags/echo.rb b/lib/liquid/tags/echo.rb
index 19026a08..7ac64aba 100644
--- a/lib/liquid/tags/echo.rb
+++ b/lib/liquid/tags/echo.rb
@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
 module Liquid
-  # Echo outputs an expression
-  #
-  #   {% echo monkey %}
-  #   {% echo user.name %}
-  #
-  # This is identical to variable output syntax, like {{ foo }}, but works
-  # inside {% liquid %} tags. The full syntax is supported, including filters:
-  #
-  #   {% echo user | link %}
-  #
+  # @public_docs
+  # @type tag
+  # @category theme
+  # @title echo
+  # @summary
+  #   Outputs an expression, or Liquid object, in the rendered HTML.
+  #   Works the same as wrapping an expression in double curly brace delimiters `{{ }}`.
+  #   Works inside the [`liquid`](/api/liquid/tags/theme-tags#liquid) tag and supports [filters](/api/liquid/filters).
+  # @syntax
+  #   {% echo 'string' %}
   class Echo < Tag
     attr_reader :variable
 
diff --git a/lib/liquid/tags/raw.rb b/lib/liquid/tags/raw.rb
index 3a5b9901..bff672db 100644
--- a/lib/liquid/tags/raw.rb
+++ b/lib/liquid/tags/raw.rb
@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
 module Liquid
+  # @public_docs
+  # @type tag
+  # @category theme
+  # @title raw
+  # @summary
+  #   Allows you to output Liquid code on a page without it being parsed.
+  # @syntax
+  #   {% raw %}
+  #     liquid
+  #   {% endraw %}
   class Raw < Block
     Syntax = /\A\s*\z/
     FullTokenPossiblyInvalid = /\A(.*)#{TagStart}\s*(\w+)\s*(.*)?#{TagEnd}\z/om
diff --git a/lib/liquid/tags/render.rb b/lib/liquid/tags/render.rb
index 6380249c..ea537d39 100644
--- a/lib/liquid/tags/render.rb
+++ b/lib/liquid/tags/render.rb
@@ -1,6 +1,29 @@
 # frozen_string_literal: true
 
 module Liquid
+
+  # @public_docs
+  # @type tag
+  # @category theme
+  # @title render
+  # @summary
+  #   Renders a snippet from the **snippets** folder of a theme, or [code for an app block](/themes/architecture/sections/section-schema#render-app-blocks).
+  #  You don't need to write the file's `.liquid` extension.
+  # @description
+  #    When a snippet is rendered, the code inside it doesn't automatically have access to the variables assigned
+  #    using [variable tags](/api/liquid/tags/variable-tags) within the snippet's parent template.
+  #    Similarly, variables assigned within the snippet can't be accessed by the code outside of the snippet.
+  #    This encapsulation increases performance and helps make theme code easier to understand and maintain.
+  #
+  #    You can't use an [`include`](/api/liquid/tags/theme-tags#include) tag inside of a snippet rendered using the `render` tag.
+  #
+  #    > Tip:
+  #    > This tag replaces the deprecated [`include`](/api/liquid/tags/theme-tags#include) tag.
+  # @syntax
+  #   {% render reference %}
+  # @optional_param with [string] Pass an object to use in the snippet. Use with the `as` parameter.
+  # @optional_param for [string] Render the snippet once for each value of an enumerable object. Use with the `as` parameter. When using the `for` parameter, the [`forloop`](/api/liquid/objects/for-loops) object is accessible within the snippet.
+  # @optional_param as [string] The variable that the object referenced by a `with` or `for` parameter represents within the snippet.
   class Render < Tag
     FOR = 'for'
     SYNTAX = /(#{QuotedString}+)(\s+(with|#{FOR})\s+(#{QuotedFragment}+))?(\s+(?:as)\s+(#{VariableSegment}+))?/o