From 9e27fef0b789b3b6994a78ad43e64ccb71c72698 Mon Sep 17 00:00:00 2001
From: Robert McLay <mclay@zaniahgroup.com>
Date: Mon, 11 Mar 2024 13:33:30 -0600
Subject: [PATCH] PR #696: describe optional third argument to hook.register()
 function

---
 docs/source/170_hooks.rst | 23 +++++++++++------------
 src/Hook.lua              |  1 +
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/source/170_hooks.rst b/docs/source/170_hooks.rst
index a9489382a..a55e35476 100644
--- a/docs/source/170_hooks.rst
+++ b/docs/source/170_hooks.rst
@@ -200,10 +200,9 @@ Registering Multiple Hook functions
 -----------------------------------
 
 Lmod 8.7.35+ supports sites registering multiple functions for a
-single hook.  For example a site may wish to register more than one
+single hook.  For example, a site may wish to register more than one
 load hook.  The function **hook.register()** now takes an optional
-third argument to control how the functions are evaluated.  For
-example::
+third argument to control how the functions are evaluated::
 
     local function load_hook_a(t)
         local frameStk  = require("FrameStk"):singleton()
@@ -223,20 +222,20 @@ example::
     hook.register("load", load_hook_b) -- overwrites the previous hook, 
 
     hook.register("load", load_hook_a)
-    hook.register("load", load_hook_b,"replace") -- overwrites the previous hook, 
+    hook.register("load", load_hook_b, "replace") -- overwrites the previous hook function, 
 
     -- > the following will run load_hook_a then load_hook_b.
-    hook.register("load", load_hook_a, "append") -- appends to the previous hook
-    hook.register("load", load_hook_b, "append") -- appends to the previous hook
+    hook.register("load", load_hook_a)           -- initializes the load hook function
+    hook.register("load", load_hook_b, "append") -- appends to the previous hook function.
 
     -- > the following will run load_hook_b then load_hook_a
-    hook.register("load", load_hook_a, "prepend") -- prepends to the previous hook
-    hook.register("load", load_hook_b, "prepend") -- prepends to the previous hook
-
-Note that if the optional third argument (the action argument) causes
-the 2nd call to hook.register to replace the first function.
+    hook.register("load", load_hook_a) -          -- initializes the load hook function
+    hook.register("load", load_hook_b, "prepend") -- prepends to the previous hook function
 
+Note that if the optional third argument (the action argument) is
+missing, causes the 2nd call or later call to hook.register to replace the
+function for a given hook name. 
 
 There are some hooks (such as groupName, SiteName, etc) that require
-return values.  The last register hook function will be used to return
+return values.  The last registered hook function will be used to return
 the value.
diff --git a/src/Hook.lua b/src/Hook.lua
index a0fd1d3b5..394cda571 100644
--- a/src/Hook.lua
+++ b/src/Hook.lua
@@ -81,6 +81,7 @@ local validT =
 -- Checks for a valid hook name and stores it if valid.
 -- @param name The name of the hook.
 -- @param func The function to store with it.
+-- @param action The kind of action.  This is an optional argument.
 local s_actionT = { append = true, prepend = true, replace = true }
 
 function M.register(name, func, action)