Improve comments

Author: theodorejb

README.md

@@ -10,7 +10,7 @@ PHP Handlebars compiles and executes complex templates up to 40% faster than Lig
 | Library            | Compile time | Runtime | Total time | Peak memory usage |
 |--------------------|--------------|---------|------------|-------------------|
 | LightnCandy 1.2.6  | 5.2 ms       | 2.8 ms  | 8.0 ms     | 5.3 MB            |
-| PHP Handlebars 1.2 | 3.7 ms       | 1.5 ms  | 5.2 ms     | 3.6 MB            |
+| PHP Handlebars 1.2 | 3.6 ms       | 1.5 ms  | 5.1 ms     | 3.6 MB            |
 
 _Tested on PHP 8.5 with the JIT enabled. See the `benchmark` branch to run the same test._
 
@@ -106,7 +106,7 @@ echo $template(['first' => 'John']); // Error: "last" not defined
 `Handlebars::compile` returns a closure which can be invoked as `$template($context, $options)`.
 The `$options` parameter takes an array of runtime options, accepting the following keys:
 
-* `data`: An associative array of initial `@data` variables (e.g. `['version' => '1.0']` makes `@version` available in the template).
+* `data`: An associative array of custom `@data` variables (e.g. `['version' => '1.0']` makes `@version` available in the template).
 
 * `helpers`: An `array<string, \Closure>` of helpers to merge with the built-in helpers. Can also be used to override a built-in helper by using the same name.
 
@@ -218,8 +218,8 @@ If a custom helper is executed in a `{{ }}` expression, the return value will be
 When a helper is executed in a `{{{ }}}` expression, the original return value will be output directly.
 
 Helpers may return a `DevTheorem\Handlebars\SafeString` instance to prevent escaping the return value.
-When constructing the string that will be marked as safe, any external content should be properly escaped
-using the `Handlebars::escapeExpression()` method to avoid potential security concerns.
+Because `SafeString` bypasses the automatic HTML escaping that `{{ }}` applies, any user-supplied content
+embedded in it must first be escaped with `Handlebars::escapeExpression()` to prevent XSS vulnerabilities.
 
 ## Data Frames
 

src/HelperOptions.php

@@ -69,6 +69,7 @@ public function fn(mixed $context = Scope::Use, mixed $data = null): string
             if ($this->inv === null) {
                 throw new \Exception('fn() is not supported for inline helpers');
             }
+            // Occurs when blockHelperMissing routes a truthy context through fn() for an inverted block.
             return '';
         }
         return $this->invokeBlock($this->cb, $context, $data);

src/Runtime.php

@@ -201,7 +201,8 @@ public static function createContext(mixed $context, array $options, array $comp
 
     /**
      * Invoke $v if it is callable, passing any extra args; otherwise return $v as-is.
-     * Used for data variables that may hold functions (e.g. {{@hello}} or {{@hello "arg"}}).
+     * Used for data variables that may hold functions (e.g. {{@hello}}) and for non-simple
+     * pathed expressions with arguments (e.g. {{./helper "arg"}}).
      */
     public static function dv(mixed $v, mixed ...$args): mixed
     {
@@ -241,18 +242,13 @@ public static function hv(RuntimeContext $cx, string $name, mixed &$_this): mixe
     }
 
     /**
-     * For {{#if}} and {{#unless}}.
-     *
-     * @param array<array<mixed>|string|int>|string|\Stringable|int|float|bool|null $v value to be tested
-     * @param bool $zero include zero as true
-     *
-     * @return bool Return true when the value is not null nor false.
+     * Returns true or false following the semantics of {{#if}} and {{#unless}} in Handlebars.js.
      */
-    public static function ifvar(mixed $v, bool $zero = false): bool
+    public static function ifvar(mixed $v, bool $includeZero = false): bool
     {
         return $v !== null
             && $v !== false
-            && ($zero || ($v !== 0 && $v !== 0.0))
+            && ($includeZero || ($v !== 0 && $v !== 0.0))
             && $v !== ''
             && (!is_array($v) || $v)
             && (!$v instanceof \Stringable || (string) $v !== '');
@@ -300,7 +296,8 @@ public static function raw(mixed $value): string
 
     /**
      * For {{#var}} and {{^var}} sections.
-     * Pass null for $cb when compiling an inverted section ({{^var}}) — blockHelperMissing will call inverse().
+     * Pass null for $cb when compiling an inverted section ({{^var}}): blockHelperMissing routes
+     * truthy contexts through fn() (which returns '' when $cb is null) and falsy contexts through inverse().
      *
      * @param mixed $in input data with current scope
      * @param \Closure|null $cb callback function to render child context; null for inverted sections
@@ -328,11 +325,6 @@ public static function sec(RuntimeContext $cx, mixed $value, mixed $in, ?\Closur
 
     /**
      * Get merged context.
-     *
-     * @param array<array<mixed>|string|int>|object|string|int|null $a the context to be merged
-     * @param array<array<mixed>|string|int|null>|string|int|null $b the new context to overwrite
-     *
-     * @return array<array<mixed>|string|int|null>|object|string|int|null the merged context object
      */
     public static function merge(mixed $a, mixed $b): mixed
     {
@@ -451,7 +443,10 @@ public static function dynhbch(RuntimeContext $cx, string $name, array $position
     }
 
     /**
-     * For single known helpers.
+     * Invoke a resolved helper Closure with positional params, hash, and a HelperOptions instance.
+     * Used for known helpers (direct hbch calls from generated code), runtime-registered helpers
+     * (called from hv()), context closures (called from dynhbch()), and built-in fallbacks like
+     * helperMissing/blockHelperMissing.
      *
      * @param array<mixed> $positional
      * @param array<string, mixed> $hash
@@ -516,8 +511,8 @@ public static function hbbch(RuntimeContext $cx, \Closure $helper, string $name,
      * @param array<mixed> $positional
      * @param array<string, mixed> $hash
      * @param array<string,array<mixed>|string|int> $_this current rendering context for the helper
-     * @param \Closure $cb callback function to render child context
-     * @param \Closure|null $else callback function to render child context when {{else}}
+     * @param \Closure|null $cb callback function to render main block; null for inverted sections with params/hash
+     * @param \Closure|null $else callback function to render {{else}}
      * @param array<mixed> $outerBlockParams outer block param stack for block params declared by the template
      */
     public static function dynhbbch(RuntimeContext $cx, string $name, mixed $callable, array $positional, array $hash, mixed &$_this, ?\Closure $cb, ?\Closure $else, int $blockParamCount, array $outerBlockParams): mixed

src/SafeString.php

@@ -4,8 +4,9 @@
 
 /**
  * Can be returned from a custom helper to prevent an HTML string from being escaped
- * when the template is rendered. When constructing, any external content should be
- * properly escaped using Handlebars::escapeExpression() to avoid potential security concerns.
+ * when the template is rendered. Because SafeString bypasses the automatic HTML escaping
+ * that {{ }} applies, any user-supplied content embedded in it must first be escaped with
+ * Handlebars::escapeExpression() to prevent XSS vulnerabilities.
  */
 class SafeString implements \Stringable
 {