Update API docs for hooks

Zotlabs/Extend/Hook.php

@@ -1,15 +1,57 @@
 <?php
+/*
+ * SPDX-FileCopyrightText: 2025 The Hubzilla Community
+ * SPDX-FileContributor: redmatrix
+ * SPDX-FileContributor: Klaus Weidenbach
+ * SPDX-FileContributor: zotlabs
+ * SPDX-FileContributor: Harald Eilertsen <haraldei@anduin.net>
+ *
+ * SPDX-License-Identifier: MIT
+ */
 
 namespace Zotlabs\Extend;
 
 use App;
 
 /**
- * @brief Hook class.
+ * A class for hooking into Hubzilla.
  *
+ * Hooks are functions that Hubzilla will invoke at certain points in the code
+ * during execution. An addon can register a callback  handler that will be
+ * called whenever the specified hook is invoked. A callback handler is a
+ * function that takes a reference to an array containing the callback
+ * arguments as it's only argument.
+ *
+ * @see call_hooks
+ * @see load_hooks
  */
 class Hook {
 
+	/**
+	 * Register a callback handler for a hook.
+	 *
+	 * A callback handler is a function that takes a reference to an array
+	 * containing the callback arguments as it's only argument.
+	 *
+	 * The contents and meaning of the array depends on the hook invoked. By
+	 * modifying the contents of the array the hook can pass data back to the
+	 * caller.
+	 *
+	 * Once the `Hook::register` function has been called, the callback may be
+	 * invoked.
+	 *
+	 * @param string $hook		The name of the hook to register a handler for.
+	 * @param string $file		The source file of the callback handler.
+	 * @param string|array $function
+	 *                          The function name of the callback handler, as a
+	 *                          string or an array.
+	 * @param int $version		Hook interface version, allways 1.
+	 * @param int $priority		The priority of the callback handler, higher
+	 *                          numbers takes precedence.
+	 *
+	 * @return true if the handler was already registered, otherwise the result
+	 *		from inserting the hook in the database.
+	 */
 	static public function register($hook,$file,$function,$version = 1,$priority = 0) {
 		if(is_array($function)) {
 			$function = serialize($function);
@@ -45,6 +87,14 @@ class Hook {
 		return $r;
 	}
 
+	/**
+	 * Register an array of hook callback handlers.
+	 *
+	 * All of the handlers must be in the same source file.
+	 *
+	 * @param string $file	The source file of the callback handlers.
+	 * @param array $arr	An array of `hookname => functionname` pairs.
+	 */
 	static public function register_array($file,$arr) {
 		if($arr) {
 			foreach($arr as $k => $v) {
@@ -54,6 +104,20 @@ class Hook {
 	}
 
 
+	/**
+	 * Unregister a hook callback handler.
+	 *
+	 * @param string $hook		The name of the hook to register a callback handler for.
+	 * @param string $file		The source file of the hook callback handler.
+	 * @param string|array $function
+	 *                          The function name of the callback handler, as a
+	 *                          string or an array.
+	 * @param int $version		Hook interface version, allways 1.
+	 * @param int $priority		The priority of the callback handler, higher
+	 *                          numbers takes precedence.
+	 *
+	 * @return The result of the database delete operation.
+	 */
 	static public function unregister($hook,$file,$function,$version = 1,$priority = 0) {
 		if(is_array($function)) {
 			$function = serialize($function);
@@ -70,11 +134,13 @@ class Hook {
 	}
 
 	/**
-	 * @brief Unregister all hooks with this file component.
+	 * Unregister all hooks handlers from a given source file.
 	 *
 	 * Useful for addon upgrades where you want to clean out old interfaces.
 	 *
-	 * @param string $file
+	 * @param string $file		The source file where the hook handlers were defined.
+	 *
+	 * @return The result from the database delete operation.
 	 */
 	static public function unregister_by_file($file) {
 		$r = q("DELETE FROM hook WHERE file = '%s' ",
@@ -85,25 +151,20 @@ class Hook {
 	}
 
 	/**
-	 * @brief Inserts a hook into a page request.
+	 * Inserts a hook into a page request.
 	 *
-	 * Insert a short-lived hook into the running page request.
+	 * Insert a short-lived hook into the running page request. Hooks are
-	 * Hooks are normally persistent so that they can be called
+	 * normally persistent so that they can be called across asynchronous
-	 * across asynchronous processes such as delivery and poll
+	 * processes such as delivery and poll processes.
-	 * processes.
 	 *
-	 * insert_hook lets you attach a hook callback immediately
+	 * This function lets you attach a hook callback immediately which will not
-	 * which will not persist beyond the life of this page request
+	 * persist beyond the life of this page request or the current process.
-	 * or the current process.
 	 *
-	 * @param string $hook
+	 * @param string $hook		Name of hook to attach callback.
-	 *     name of hook to attach callback
+	 * @param string|array $fn	Name of callback handler as a string or array.
-	 * @param string $fn
+	 * @param int $version		Hook interface version, allways 1.
-	 *     function name of callback handler
+	 * @param int $priority		Currently not implemented in this function,
-	 * @param int $version
+	 *                          would require the hook array to be resorted.
-	 *     hook interface version, 0 uses two callback params, 1 uses one callback param
-	 * @param int $priority
-	 *     currently not implemented in this function, would require the hook array to be resorted
 	 */
 	static public function insert($hook, $fn, $version = 0, $priority = 0) {
 		if(is_array($fn)) {
@@ -119,4 +180,4 @@ class Hook {
 		App::$hooks[$hook][] = array('', $fn, $priority, $version);
 	}
 
-}
+}

include/plugin.php

@@ -382,14 +382,19 @@ function unregister_hook($hook, $file, $function) {
 }
 
 /**
- * @brief loads all active hooks into memory
+ * Loads all active hooks into memory.
- * alters: App::$hooks
+ *
- * Called during initialisation
+ * Called during initialisation.
  * Duplicated hooks are removed and the duplicates ignored
  *
  * It might not be obvious but themes can manually add hooks to the App::$hooks
  * array in their theme_init() and use this to customise the app behaviour.
  * use insert_hook($hookname,$function_name) to do this.
+ *
+ * @sideeffect Alters global variable `App::$hooks`
+ *
+ * @see Zotlabs::Extend::Hook
+ * @see call_hooks
  */
 function load_hooks() {
 
@@ -453,13 +458,16 @@ function insert_hook($hook, $fn, $version = 0, $priority = 0) {
 }
 
 /**
- * @brief Calls a hook.
+ * Call all registered callbacks for a named hook.
  *
- * Use this function when you want to be able to allow a hook to manipulate
+ * Use this function when you want to be able to allow a hook to manipulate the
- * the provided data.
+ * provided data.
  *
- * @param string $name of the hook to call
+ * @param string $name					Name of the hook to call.
- * @param[in,out] string|array &$data to transmit to the callback handler
+ * @param[in,out] string|array &$data	Data to transmit to the callback handler.
+ *
+ * @see Zotlabs::Extend::Hook
+ * @see load_hooks
  */
 function call_hooks($name, &$data = null) {
 	if (isset(App::$hooks[$name])) {