[latex3-commits] [git/LaTeX3-latex3-latex3] main: Improve doc of some functions that also assign a tl (fixes #1017) (06cc90433)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/06cc90433dec91494fcfef20cf9d90ff90544186

>---------------------------------------------------------------

commit 06cc90433dec91494fcfef20cf9d90ff90544186
Author: Bruno Le Floch <blflatex at gmail.com>
Date:   Mon Nov 15 13:12:12 2021 +0100

    Improve doc of some functions that also assign a tl (fixes #1017)


>---------------------------------------------------------------

06cc90433dec91494fcfef20cf9d90ff90544186
 l3kernel/l3regex.dtx | 10 ++++++----
 l3kernel/l3tl.dtx    | 15 ++++++++-------
 2 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/l3kernel/l3regex.dtx b/l3kernel/l3regex.dtx
index ac70e76ee..3df874e93 100644
--- a/l3kernel/l3regex.dtx
+++ b/l3kernel/l3regex.dtx
@@ -711,11 +711,12 @@
 %     \cs{regex_replace_once:nnN} \Arg{regular expression} \Arg{replacement} \meta{tl~var}
 %     \cs{regex_replace_once:nnNTF} \Arg{regular expression} \Arg{replacement} \meta{tl~var} \Arg{true code} \Arg{false code}
 %   \end{syntax}
-%   Searches for the \meta{regular expression} in the \meta{token list}
-%   and replaces the first match with the \meta{replacement}. The result
-%   is assigned locally to \meta{tl~var}. In the \meta{replacement},
+%   Searches for the \meta{regular expression} in the contents of the
+%   \meta{tl~var} and replaces the first match with the
+%   \meta{replacement}. In the \meta{replacement},
 %   |\0| represents the full match, |\1| represent the contents of the
 %   first capturing group, |\2| of the second, \emph{etc.}
+%   The result is assigned locally to \meta{tl~var}.
 % \end{function}
 %
 % \begin{function}[noTF, added = 2017-05-26]
@@ -725,7 +726,8 @@
 %     \cs{regex_replace_all:nnNTF} \Arg{regular expression} \Arg{replacement} \meta{tl~var} \Arg{true code} \Arg{false code}
 %   \end{syntax}
 %   Replaces all occurrences of the \meta{regular expression} in the
-%   \meta{token list} by the \meta{replacement}, where |\0| represents
+%   contents of the \meta{tl~var}
+%   by the \meta{replacement}, where |\0| represents
 %   the full match, |\1| represent the contents of the first capturing
 %   group, |\2| of the second, \emph{etc.} Every match is treated
 %   independently, and matches cannot overlap.  The result is assigned
diff --git a/l3kernel/l3tl.dtx b/l3kernel/l3tl.dtx
index bda39b5cf..48c320f77 100644
--- a/l3kernel/l3tl.dtx
+++ b/l3kernel/l3tl.dtx
@@ -584,14 +584,16 @@
 %   \begin{syntax}
 %     \cs{tl_reverse:N} \meta{tl~var}
 %   \end{syntax}
-%   Reverses the order of the \meta{items} stored in \meta{tl~var}, so
+%   Sets the \meta{tl~var} to contain the result of reversing
+%   the order of its \meta{items}, so
 %   that \meta{item_1}\meta{item_2}\meta{item_3} \ldots \meta{item_n}
 %   becomes \meta{item_n}\ldots \meta{item_3}\meta{item_2}\meta{item_1}.
 %   This process preserves unprotected spaces within the
 %   \meta{token list variable}. Braced token groups are copied without
 %   reversing the order of tokens, but keep the outer set of braces.
-%   See also \cs{tl_reverse:n}, and, for improved performance,
-%   \cs{tl_reverse_items:n}.
+%   This is equivalent to a combination of an assignment and
+%   \cs{tl_reverse:V}.  See also \cs{tl_reverse_items:n} for improved
+%   performance.
 % \end{function}
 %
 % \begin{function}[added = 2012-01-08, EXP]{\tl_reverse_items:n}
@@ -649,10 +651,9 @@
 %   \begin{syntax}
 %     \cs{tl_trim_spaces:N} \meta{tl~var}
 %   \end{syntax}
-%   Removes any leading and trailing explicit space characters
-%   (explicit tokens with character code~$32$ and category code~$10$)
-%   from the content of the \meta{tl~var}. Note that this therefore
-%   \emph{resets} the content of the variable.
+%   Sets the \meta{tl~var} to contain the result of removing any leading
+%   and trailing explicit space characters (explicit tokens with
+%   character code~$32$ and category code~$10$) from its contents.
 % \end{function}
 %
 % \subsection{Viewing token lists}