[latex3-commits] [git/LaTeX3-latex3-latex2e] hook-args: More docs (440d1de7)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : hook-args
Link       : https://github.com/latex3/latex2e/commit/440d1de707fc022c4672afb819bd078b7ca98748

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

commit 440d1de707fc022c4672afb819bd078b7ca98748
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Tue Mar 28 00:06:07 2023 -0300

    More docs


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

440d1de707fc022c4672afb819bd078b7ca98748
 base/lthooks.dtx | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 5728978f..aff30d76 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -4265,7 +4265,8 @@
 %    \end{macrocode}
 %   Here we take the existing code in the macro, expand it with as many
 %   arguments as it takes, then double the hashes so the code can be
-%   reused. \pho{Maybe can be improved.}
+%   reused. \pho{Maybe can be improved. The case of adding to an empty
+%     cs can be optimised by quickly checking \cs{cs_replacement_spec}.}
 %    \begin{macrocode}
       {
         \exp_args:NNo \exp_args:No \@@_double_hashes:n
@@ -4306,8 +4307,11 @@
 %     \@@_next_gset:nn,
 %     \@@_code_gset_aux:nnn
 %   }
-%   A simple auxiliary that defines the hook code macro
-%   \cs[no-index]{@@~\meta{hook}} with the defined number of arguments.
+%   These macros define \cs[no-index]{@@\meta{type}~\meta{hook}} (with
+%   \meta{type} being \verb|_next|, \verb|_toplevel|, or empty) with the
+%   given code and the parameters stored in
+%   \cs[no-index]{c_@@_\meta{hook}_parameter_tl} (or none, if that
+%   doesn't exist).
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_code_gset:nn
   { \@@_code_gset_aux:nnn { } }
@@ -4327,6 +4331,17 @@
       {#3}
   }
 \cs_generate_variant:Nn \@@_code_gset:nn { ne }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_normalise_cs_args:nn}
+%   This macro normalises the parameters of the macros
+%   \cs[no-index]{@@\meta{type}~\meta{hook}} to take the right number of
+%   arguments after a hook is declared.  At this point we know
+%   \cs[no-index]{c_@@_\meta{hook}_parameter_tl} exists, so use that to
+%   count the arguments and use that as \meta{parameter text} for the
+%   newly (re)defined macro.
+%    \begin{macrocode}
 \cs_new_protected:Npn \@@_normalise_cs_args:nn #1 #2
   {
     \@@_code_gset_auxi:veen