From 44e1ed32a276c1033f0efbe6706c763d963a137e Mon Sep 17 00:00:00 2001
From: Kijin Sung <kijin@kijinsung.com>
Date: Sun, 15 Oct 2023 02:30:54 +0900
Subject: [PATCH] Add better comments to template parsers

---
 .../parsers/template/TemplateParser_v1.php    | 12 +++++++++
 .../parsers/template/TemplateParser_v2.php    | 26 ++++++++++++++++---
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/common/framework/parsers/template/TemplateParser_v1.php b/common/framework/parsers/template/TemplateParser_v1.php
index 26ed36e58..5e0af850a 100644
--- a/common/framework/parsers/template/TemplateParser_v1.php
+++ b/common/framework/parsers/template/TemplateParser_v1.php
@@ -5,6 +5,18 @@ namespace Rhymix\Framework\Parsers\Template;
 use HTMLDisplayHandler;
 use Rhymix\Framework\Template;
 
+/**
+ * Template parser v1 for XE compatibility.
+ *
+ * Originally part of TemplateHandler, this parser is preserved here
+ * for bug-for-bug compatibility with XE and older versions of Rhymix.
+ * A significant part of this code dates back to the early days of XE,
+ * though Rhymix has managed to squeeze in a few new features.
+ *
+ * Except in the case of a serious security issue, there will be no change
+ * to the parsing and conversion logic, and no new features.
+ * It is strongly recommended that new templates be written in v2.
+ */
 class TemplateParser_v1
 {
 	/**
diff --git a/common/framework/parsers/template/TemplateParser_v2.php b/common/framework/parsers/template/TemplateParser_v2.php
index 9fa1a9b87..6309ea81b 100644
--- a/common/framework/parsers/template/TemplateParser_v2.php
+++ b/common/framework/parsers/template/TemplateParser_v2.php
@@ -4,22 +4,42 @@ namespace Rhymix\Framework\Parsers\Template;
 
 use Rhymix\Framework\Template;
 
+/**
+ * Template parser v2
+ *
+ * This is a new template engine, rewritten from scratch to act as a bridge
+ * between legacy XE-style templates and new Blade-style templates.
+ *
+ * It supports not only Blade directives but also a number of v1 features,
+ * such as automatic path conversion and centralized asset management,
+ * which are especially important given the modular structure of Rhymix.
+ *
+ * Commonly used elements of the v1 template language are also supported
+ * for ease of migration, while some of the older and/or more bug-prone parts
+ * of v1 have been dropped.
+ */
 class TemplateParser_v2
 {
 	/**
-	 * Store template info here.
+	 * Cache template path info here.
 	 */
 	public $template;
 	public $source_type;
 
 	/**
-	 * Temporary information for conversion.
+	 * Properties for internal bookkeeping.
 	 */
 	protected $_aliases = [];
 	protected $_stack = [];
 	protected $_uniq_order = 1;
 
-	// Loop definitions.
+	/**
+	 * Definitions of loop and condition directives.
+	 *
+	 * %s     : Full PHP code passed to the directive in parentheses.
+	 * %array : The array used in a foreach/forelse loop.
+	 * %uniq  : A random string that identifies a specific loop or condition.
+	 */
 	protected static $_loopdef = [
 		'if' => ['if (%s):', 'endif;'],
 		'unless' => ['if (!(%s)):', 'endif;'],