[latex3-commits] [git/LaTeX3-latex3-latex2e] hotfix/gh441: Code docs (c878da86)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : hotfix/gh441
Link       : https://github.com/latex3/latex2e/commit/c878da869c8b214b409bae206d90c897dbae212e

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

commit c878da869c8b214b409bae206d90c897dbae212e
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Thu Dec 10 14:17:11 2020 -0300

    Code docs


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

c878da869c8b214b409bae206d90c897dbae212e
 base/lthooks.dtx | 33 +++++++++++++++++++++++----------
 1 file changed, 23 insertions(+), 10 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 3021e107..f6de5408 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -1896,9 +1896,9 @@
 % \begin{macro}{\@@_declare:n}
 %   This function declares the basic data structures for a hook without
 %   actually declaring the hook itself.  This is needed to allow adding
-%   to undeclared hooks.  Here it is unnecessary to check whether both
-%   variables exist, since both are declared at the same time (either
-%   both exist, or neither).
+%   to undeclared hooks.  Here it is unnecessary to check whether all
+%   variables exist, since all three are declared at the same time
+%   (either all of them exist, or none).
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_declare:n #1
   {
@@ -2220,7 +2220,10 @@
 %    \end{macrocode}
 %    Then try to get the code chunk labeled \verb=#2= from the hook.
 %    If there's code already there, then append \verb=#3= to that,
-%    otherwise just put \verb=#3=.
+%    otherwise just put \verb=#3=.  If the current label is |top-level|,
+%    the code is added to a dedicated token list
+%    \cs[no-index]{@@_toplevel~\meta{hook}} that goes at the end of the
+%    hook, just before \cs[no-index]{@@_next~\meta{hook}}.
 %    \begin{macrocode}
     \str_if_eq:nnTF {#2} { top-level }
       {
@@ -2456,6 +2459,12 @@
 %    \begin{macrocode}
       {
         \debug_suspend:
+%    \end{macrocode}
+%    If all code is to be removed, clear the code pool
+%    \cs[no-index]{g_@@_\meta{hook}_code_prop}, the top-level code
+%    \cs[no-index]{@@_toplevel~\meta{hook}}, and the next-execution code
+%    \cs[no-index]{@@_next~\meta{hook}}.
+%    \begin{macrocode}
         \str_if_eq:nnTF {#2} {*}
           {
             \prop_gclear:c { g_@@_#1_code_prop }
@@ -2491,6 +2500,8 @@
 %    \end{macrocode}
 %
 % \begin{macro}{\@@_gremove_code_do:nn}
+%   Remove code for a given label.  If the label is |top-level| then
+%   clear the token list, as all code there is under the same label.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_gremove_code_do:nn #1 #2
   {
@@ -2840,8 +2851,8 @@
 %    If there aren't any code
 %    chunks for the current hook, there is no point in even starting
 %    the sorting routine so we make a quick test for that and in that
-%    case just update \cs{@@~\meta{hook}} to hold the |next|
-%    code. If there are code chunks we call
+%    case just update \cs{@@~\meta{hook}} to hold the |top-level| and
+%    |next| code chunks. If there are code chunks we call
 %    \cs{@@_initialize_single:NNNNn} and pass to it ready made csnames
 %    as they are needed several times inside. This way we save a bit
 %    on processing time if we do that up front.
@@ -3115,8 +3126,8 @@
       }
 %    \end{macrocode}
 %    After we have added all hook code to \verb=#1= we finish it off
-%    with adding extra code for a one time execution. That is stored
-%    in \verb=#3= but is normally empty.
+%    with adding extra code for the |top-level| (\verb=#2=) and for one
+%    time execution (\verb=#3=).  These should normally be empty.
 %    \begin{macrocode}
     \tl_gput_right:Nn #1 { #2 #3 }
   }
@@ -3395,6 +3406,7 @@
           }
 %    \end{macrocode}
 %
+%    If there is code in the |top-level| token list, print it:
 %    \begin{macrocode}
         \@@_log_line:x { Document-level~(top-level)~code:}
         \@@_log_line_indent:x
@@ -3766,8 +3778,9 @@
 %
 % \begin{macro}[pTF]{\hook_if_empty:n}
 %   Test if a hook is empty (that is, no code was added to that hook).
-%   A hook being empty means that \emph{both} its
-%   \cs[no-index]{g_@@_\meta{hook}_code_prop} and its
+%   A \meta{hook} being empty means that all three of its
+%   \cs[no-index]{g_@@_\meta{hook}_code_prop}, its
+%   \cs[no-index]{@@_toplevel~\meta{hook}} and its
 %   \cs[no-index]{@@_next~\meta{hook}} are empty.
 %    \begin{macrocode}
 \prg_new_conditional:Npnn \hook_if_empty:n #1 { p , T , F , TF }