From 97abc313b6a7f82f19c4f8325c26cb2195c6a533 Mon Sep 17 00:00:00 2001
From: Leonidas Zhak <70497898+LeonidasZhak@users.noreply.github.com>
Date: Sun, 7 Jun 2026 12:11:50 +0800
Subject: [PATCH] docs: fix shift.Rd Value section to reflect vector return for
 single n

The Value section previously stated 'A list containing the lead/lag of
input x', but shift() returns a vector (not a list) when x is atomic
and length(n) == 1. This is confirmed by src/shift.c:181:
  if (isVectorAtomic(obj) && length(ans) == 1) ans = VECTOR_ELT(ans, 0);

The inaccurate Value section could confuse Stata migrants expecting
consistent return types from lag/lead operations.
---
 man/shift.Rd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/shift.Rd b/man/shift.Rd
index 7815b32849..35268411ea 100644
--- a/man/shift.Rd
+++ b/man/shift.Rd
@@ -29,7 +29,7 @@ shift(x, n=1L, fill, type=c("lag", "lead", "shift", "cyclic"), give.names=FALSE)
   Note that when using \code{shift} with a list, it should be a list of lists rather than a flattened list. The function was not designed to handle flattened lists directly. This also applies to the use of list columns in a data.table. For example, \code{DT = data.table(x=as.list(1:4))} is a data.table with four rows. Applying \code{DT[, shift(x)]} now lags every entry individually, rather than shifting the full columns like \code{DT[, shift(as.integer(x))]} does. Using \code{DT = data.table(x=list(1:4))} creates a data.table with one row. Now \code{DT[, shift(x)]} returns a data.table with four rows where x is lagged. To get a shifted data.table with the same number of rows, wrap the \code{shift} function in \code{list} or \code{dot}, e.g., \code{DT[, .(shift(x))]}.
 }
 \value{
-  A list containing the lead/lag of input \code{x}.
+  When \code{x} is a vector and \code{length(n) == 1}, a vector of the same type and length as \code{x}. Otherwise, a list of vectors (one element for each combination of input column and \code{n} value).
 }
 
 \examples{