[latex3-commits] [l3svn] r6013 - Clarify some code comments.

[noreply at latex-project.org]

Author: bruno
Date: 2015-09-19 01:28:16 +0200 (Sat, 19 Sep 2015)
New Revision: 6013

Modified:
   trunk/l3kernel/l3str.dtx
Log:
Clarify some code comments.


Modified: trunk/l3kernel/l3str.dtx
===================================================================
--- trunk/l3kernel/l3str.dtx	2015-09-18 15:29:35 UTC (rev 6012)
+++ trunk/l3kernel/l3str.dtx	2015-09-18 23:28:16 UTC (rev 6013)
@@ -224,7 +224,7 @@
 %     \cs{str_if_empty:NTF} \meta{str~var} \Arg{true code} \Arg{false code}
 %   \end{syntax}
 %   Tests if the \meta{string variable} is entirely empty
-%   (\emph{i.e.}~contains no tokens at all).
+%   (\emph{i.e.}~contains no characters at all).
 % \end{function}
 %
 % \begin{function}[EXP,pTF, added = 2015-09-18]
@@ -846,10 +846,6 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}[int, EXP]{\@@_if_eq_x_return:nn}
-%   Defined in \pkg{l3basics}.
-% \end{macro}
-%
 % \begin{macro}[EXP, pTF]
 %   {\str_if_eq:NN, \str_if_eq:Nc, \str_if_eq:cN, \str_if_eq:cc}
 %   Note that \cs{str_if_eq:NN} is different from
@@ -990,19 +986,19 @@
 %   The \cs{str_item:nn} hands its argument with spaces escaped to
 %   \cs{@@_item:nn}, and makes sure to turn the result back into
 %   a proper string (with category code~$10$ spaces) eventually.  The
-%   \cs{str_item_ignore_spaces:nn} function cheats a little bit in that
-%   it doesn't hand to \cs{@@_item:nn} an \enquote{other string}.
-%   This is safe, as everything else is done with undelimited arguments.
-%   Then evaluate the \meta{index} argument~|#2| and count characters in
-%   the string, passing those two numbers to \cs{@@_item:ww} for further
-%   analysis.  If the \meta{index} is negative, shift by |#2|, and
-%   remove that number of characters before returning the next item in
-%   the input stream (and if |#1| is smaller than $-|#2|$, nothing is
-%   returned).  If the \meta{index} is positive, ignore that number
-%   (minus one) of characters before returning the next one.  The shift
-%   by one is obtained by inserting an empty brace group before the
-%   string in that case: that brace group also covers the case where the
-%   \meta{index} is zero.
+%   \cs{str_item_ignore_spaces:nn} function does not escape spaces,
+%   which are thus ignored by \cs{@@_item:nn} since
+%   everything else is done with undelimited arguments.
+%   Evaluate the \meta{index} argument~|#2| and count characters in
+%   the string, passing those two numbers to \cs{@@_item:ww} for
+%   further analysis.  If the \meta{index} is negative, shift it by
+%   the \meta{count} to know the how many character to discard, and if
+%   that is still negative give an empty result.  If the \meta{index}
+%   is larger than the \meta{count}, give an empty result, and
+%   otherwise discard $\meta{index}-1$ characters before returning the
+%   following one.  The shift by $-1$ is obtained by inserting an empty
+%   brace group before the string in that case: that brace group also
+%   covers the case where the \meta{index} is zero.
 %    \begin{macrocode}
 \cs_new_nopar:Npn \str_item:Nn { \exp_args:No \str_item:nn }
 \cs_generate_variant:Nn \str_item:Nn { c }
@@ -1258,9 +1254,10 @@
 %   longer than token lists, we use specialized functions to count
 %   characters ignoring spaces.  Namely, loop, grabbing $9$ non-space
 %   characters at each step, and end as soon as we reach one of the $9$
-%   trailing items.  The \texttt{_unsafe} variant expects a token list
-%   already converted to category code $12$ characters, and is used by
-%   \cs{str_item:nn}.
+%   trailing items.  The internal function \cs{@@_count:n}, used in
+%   \cs{str_item:nn} and \cs{str_range:nnn}, is similar to
+%   \cs{str_count_ignore_spaces:n} but expects its argument to already
+%   be a string or a string with spaces escaped.
 %    \begin{macrocode}
 \cs_new_nopar:Npn \str_count:N { \exp_args:No \str_count:n }
 \cs_generate_variant:Nn \str_count:N { c }
@@ -1310,8 +1307,9 @@
 % \begin{macro}[EXP]
 %   {\str_head:N, \str_head:c, \str_head:n, \str_head_ignore_spaces:n}
 % \begin{macro}[EXP, aux]{\@@_head:w}
-%   The \texttt{_ignore_spaces} variant is almost identical to
-%   \cs{tl_head:n}.  As usual, \cs{str_head:N} expands its argument and
+%   The \texttt{_ignore_spaces} variant applies \cs{tl_to_str:n} then
+%   grabs the first item, thus skipping spaces.
+%   As usual, \cs{str_head:N} expands its argument and
 %   hands it to \cs{str_head:n}.  To circumvent the fact that \TeX{}
 %   skips spaces when grabbing undelimited macro parameters,
 %   \cs{@@_head:w} takes an argument delimited by a space. If |#1|
@@ -1461,7 +1459,7 @@
 %     \c_left_brace_str,
 %     \c_right_brace_str,
 %     \c_circumflex_str,
-%     \c_colojn_str,
+%     \c_colon_str,
 %     \c_hash_str,
 %     \c_percent_str,
 %     \c_tilde_str,