some tags

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

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

lib/liquid/tags/echo.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
 module Liquid
-  # Echo outputs an expression
+  # @public_docs
-  #
+  # @type tag
-  #   {% echo monkey %}
+  # @category theme
-  #   {% echo user.name %}
+  # @title echo
-  #
+  # @summary
-  # This is identical to variable output syntax, like {{ foo }}, but works
+  #   Outputs an expression, or Liquid object, in the rendered HTML.
-  # inside {% liquid %} tags. The full syntax is supported, including filters:
+  #   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).
-  #   {% echo user | link %}
+  # @syntax
-  #
+  #   {% echo 'string' %}
   class Echo < Tag
     attr_reader :variable
 

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

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