[latex3-commits] [git/LaTeX3-latex3-latex3] main: Corrected documentation of l3doc function environment (thanks to Jan Braun) (25523bf14)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/25523bf1497a3fb3f8868bb1ce8861f6b9e0fae6

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

commit 25523bf1497a3fb3f8868bb1ce8861f6b9e0fae6
Author: Bruno Le Floch <blflatex at gmail.com>
Date:   Wed Mar 9 10:49:59 2022 +0100

    Corrected documentation of l3doc function environment (thanks to Jan Braun)


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

25523bf1497a3fb3f8868bb1ce8861f6b9e0fae6
 l3kernel/l3doc.dtx | 62 ++++++++++++++++++++++++++++++++----------------------
 1 file changed, 37 insertions(+), 25 deletions(-)

diff --git a/l3kernel/l3doc.dtx b/l3kernel/l3doc.dtx
index e3251058b..6175fda21 100644
--- a/l3kernel/l3doc.dtx
+++ b/l3kernel/l3doc.dtx
@@ -361,69 +361,81 @@ and all files in that bundle must be distributed together.
 % \subsection{Describing functions in the documentation}
 %
 % \DescribeEnv{function}
+% \DescribeEnv{variable}
+% Two heavily-used environments are defined to describe \pkg{expl3} functions
+% and variables.  If describing a variable, use the latter environment; it
+% behaves identically to the \env{function} environment.
 % \DescribeEnv{syntax}
-% Two heavily-used environments are defined to describe the syntax of
-% \pkg{expl3} functions and variables.
+% Both of the above environments are typically combined with the \env{syntax}
+% environment, to describe their syntax.
 % \begin{framed}
 %   \vspace{-\baselineskip}
 % \begin{verbatim}
-% \begin{function}{\function_one:, \function_two:}
+% \begin{function}{\package_function_one:N, \package_function_two:n}
 %   \begin{syntax}
-%     |\foo_bar:| \Arg{meta} \meta{test_1}
+%     \cs{package_function_one:N} \meta{cs}
+%     \cs{package_function_two:n} \marg{Argument}
 %   \end{syntax}
-% \meta{description}
+% Descriptive text here ...
 % \end{function}
 % \end{verbatim}
 %   \hrulefill
 %   \par
 %   \hspace*{0.25\textwidth}
 %   \begin{minipage}{0.5\textwidth}
-%     \begin{function}{\function_one:, \function_two:}
+%     \begin{function}{\package_function_one:N, \package_function_two:n}
 %       \begin{syntax}
-%         |\foo_bar:| \Arg{meta} \meta{test_1}
+%         \cs[no-index]{package_function_one:N} \meta{cs}
+%         \cs[no-index]{package_function_two:n} \marg{Argument}
 %       \end{syntax}
-%       \meta{description}
+%       \emph{Descriptive text here …}
 %     \end{function}
 %   \end{minipage}
 % \end{framed}
 %
 % Function environments take an optional argument to indicate whether
-% the function(s) it describes are expandable or restricted-expandable
-% or defined in conditional forms. Use |EXP|, |rEXP|, |TF|, |pTF|, or |noTF| for
-% this; note that |pTF| implies |EXP| since predicates must always be
-% expandable, and that |noTF| means that the function without |TF|
-% should be documented in addition to |TF|.  As an example:
+% the function(s) it describes are expandable (use |EXP|) or
+% restricted-expandable (use |rEXP|) or defined in conditional forms
+% (use |TF|, |pTF|, or |noTF|).  Note that |pTF| implies |EXP| since
+% predicates must always be expandable, and that |noTF| means that the
+% function without |TF| should be documented in addition to |TF|.  For
+% the conditional forms |TF| and |pTF|, the argument of the
+% \env{function} environment is \emph{not} in fact a command that
+% exists: in the example below, \cs[no-index]{tl_if_empty:N} does not
+% exist, but its conditional forms \cs{tl_if_empty:NT},
+% \cs{tl_if_empty:NF}, \cs{tl_if_empty:NTF} and predicate form
+% \cs{tl_if_empty_p:N} exist:
 % \begin{framed}
 %   \vspace{-\baselineskip}
 % \begin{verbatim}
-% \begin{function}[pTF]{\cs_if_exist:N}
+% \begin{function}[pTF]{\tl_if_empty:N, \tl_if_empty:c}
 %   \begin{syntax}
-%     \cs{cs_if_exist_p:N} \meta{cs}
+%     \cs{tl_if_empty_p:N} \meta{tl~var}
+%     \cs{tl_if_empty:NTF} \meta{tl~var} \Arg{true code} \Arg{false code}
 %   \end{syntax}
-% \meta{description}
+%   Tests if the \meta{token list variable} is entirely empty
+%   (\emph{i.e.}~contains no tokens at all).
 % \end{function}
 % \end{verbatim}
 %   \hrulefill
 %   \par
 %   \hspace*{0.25\textwidth}
 %   \begin{minipage}{0.5\textwidth}
-%     \begin{function}[pTF]{\cs_if_exist:N}
+%     \begin{function}[pTF]{\tl_if_empty:N, \tl_if_empty:c}
 %       \begin{syntax}
-%         \cs{cs_if_exist_p:N} \meta{cs}
+%         \cs{tl_if_empty_p:N} \meta{tl~var}
+%         \cs{tl_if_empty:NTF} \meta{tl~var} \Arg{true code} \Arg{false code}
 %       \end{syntax}
-%       \meta{description}
+%       Tests if the \meta{token list variable} is entirely empty
+%       (\emph{i.e.}~contains no tokens at all).
 %     \end{function}
 %   \end{minipage}
 % \end{framed}
 %
-% \DescribeEnv{variable}
-% If you are documenting a variable instead of a function, use the
-% \env{variable} environment instead; it behaves identically to the
-% \env{function} environment above.
-%
 % \DescribeEnv{texnote}
 % This environment is used to call out sections within \env{function}
-% and similar that are only of interest to seasoned \TeX{} developers.
+% and similar environments that are only of interest to seasoned
+% \TeX{} developers.
 %
 % \subsection{Describing functions in the implementation}
 %