[latex3-commits] [git/LaTeX3-latex3-latex2e] ProvideHook: bit more documentation of the code (8aef8a11)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : ProvideHook
Link       : https://github.com/latex3/latex2e/commit/8aef8a11897f4905287046bb2cf272c640c78504

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

commit 8aef8a11897f4905287046bb2cf272c640c78504
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Fri Apr 30 11:15:46 2021 +0200

    bit more documentation of the code


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

8aef8a11897f4905287046bb2cf272c640c78504
 base/lthooks.dtx | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 26a846b4..e7111234 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -2432,12 +2432,6 @@
   {
     \tl_gclear_new:c { g_@@_#1_declared_tl }
     \cs_undefine:c { @@~#1 }
-%    \end{macrocode}
-%    The next lines would be needed if the \cs{hook_provide:n}
-%    commands should ignore the disabled state.
-%    \begin{macrocode}
-%    \tl_if_exist:cF { g_@@_#1_reversed_tl }
-%                    { \tl_new:c { g_@@_#1_reversed_tl } }
   }
 \prg_new_conditional:Npnn \@@_if_disabled:n #1 { p, T, F, TF }
   {
@@ -2465,8 +2459,10 @@
 % \begin{macro}{\hook_provide:n}
 % \begin{macro}{\hook_provide_reversed:n}
 % \begin{macro}{\@@_provide:n}
-%    The \cs{hook_provide:n} declaration declares a new hook and expects
-%    the hook \meta{name} as its argument, e.g.,
+%    The \cs{hook_provide:n} declaration declares a new hook if it
+%    wasn't declared already, in which case it only checks that the
+%    already existing hook is not a reversed hook.
+%    The \cs{hook_provide_reversed:n} does the same for reversed hooks.
 %    \hook{begindocument}.
 %    \begin{macrocode}
 %<latexrelease>\IncludeInRelease{2021/06/01}%
@@ -2483,14 +2479,29 @@
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_provide:nn #1 #2
   {
+%    \end{macrocode}
+%    If the hook to be provided was disabled we warn (for now --- this
+%    may change).
+%    \begin{macrocode}
     \@@_if_disabled:nTF {#1}
       { \__kernel_msg_warning:nnn { hooks } { provide-disabled } {#1} }
+%    \end{macrocode}
+%    Otherwise we check if it was already declared.
+%    \begin{macrocode}
       {
         \@@_if_declared:nTF {#1}
           {
+%    \end{macrocode}
+%    Issue an error if we try to provide a a hook that is reversed and
+%    the already existing one is not (or vice versa).
+%    \begin{macrocode}
             \str_if_eq:eeF { \tl_use:c { g_@@_#1_reversed_tl } } {#2}
               { \__kernel_msg_error:nnn { hooks } { provide-error } {#1} }
           }
+%    \end{macrocode}
+%    If it wasn't declared, we declared as a normal or reversed hook
+%    as appropriate.
+%    \begin{macrocode}
           {
             \tl_new:c { g_@@_#1_declared_tl }
             \@@_make_usable:n {#1}