From e42354ef4499390d693af27f5f23b3f47a1de6d7 Mon Sep 17 00:00:00 2001
From: Leonidas Zhak <70497898+LeonidasZhak@users.noreply.github.com>
Date: Sun, 7 Jun 2026 10:09:04 +0800
Subject: [PATCH] docs: fix inaccurate eager-eval claims in fcase.Rd

The Details section claimed that values are always evaluated regardless
of whether their condition is TRUE, and that default is always evaluated.
Both claims are wrong: fcase short-circuits once all elements are decided,
so later pairs (and default) are never reached.

Also fix the example comment from 'Lazy evaluation example' to
'Short-circuit: last value not evaluated when all elements are
already decided', which accurately describes the C implementation
(fifelse.c:407: if (l==0) break).

Verified with side-effect tests: values in reached pairs are always
evaluated eagerly, but values in unreached pairs are not evaluated.
---
 man/fcase.Rd | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/man/fcase.Rd b/man/fcase.Rd
index 466f3dfc67..85f4cf6353 100644
--- a/man/fcase.Rd
+++ b/man/fcase.Rd
@@ -12,9 +12,9 @@
 \item{default}{ Default return value, \code{NA} by default, for when all of the logical conditions \code{when1, when2, ..., whenN} are \code{FALSE} or missing for some entries. }
 }
 \details{
-\code{fcase} evaluates each when-value pair in order, until it finds a \code{when} that is \code{TRUE}. It then returns the corresponding \code{value}. During evaluation, \code{value} will be evaluated regardless of whether the corresponding \code{when} is \code{TRUE} or not, which means recursive calls should be placed in the last when-value pair, see \code{Examples}.
+\code{fcase} evaluates each when-value pair in order, until it finds a \code{when} that is \code{TRUE}. It then returns the corresponding \code{value}. Each \code{value} is evaluated eagerly when its pair is reached, regardless of whether the corresponding \code{when} is \code{TRUE} for any element. However, \code{fcase} stops processing once every element has been assigned, so later pairs may not be reached at all. This is why recursive calls should be placed in the last when-value pair, see \code{Examples}.
 
-\code{default} is always evaluated, regardless of whether it is returned or not.
+\code{default} is evaluated only when some elements remain undecided after processing all when-value pairs.
 }
 \value{
   Vector with the same length as the logical conditions (\code{when}) in \code{...}, filled with the corresponding values (\code{value}) from \code{...}, or eventually \code{default}. Attributes of output values \code{value1, value2, ...valueN} in \code{...} are preserved.
@@ -34,7 +34,7 @@ fcase(
 	x > 5L, 3L:12L
 )
 
-# Lazy evaluation example
+# Short-circuit: last value not evaluated when all elements are already decided
 fcase(
 	x < 5L, 1L,
 	x >= 5L, 3L,