docs: Revise hooks overview section

doc/api/hooks_overview.md

@@ -1,11 +1,51 @@
 # Hooks
-All hooks are called with two arguments:
 
-1. name - the name of the hook being called
-2. context - an object with some relevant information about the context of the call
+A hook function is registered with a hook via the plugin's `ep.json` file. See
+the Plugins section for details. A hook may have many registered functions from
+different plugins.
+
+When a hook is invoked, its registered functions are called with three
+arguments:
+
+1. hookName - The name of the hook being invoked.
+2. context - An object with some relevant information about the context of the
+   call. See the hook-specific documentation for details.
+3. callback - Function to call when done. This callback takes a single argument,
+   the meaning of which depends on the hook. See the "Return values" section for
+   general information that applies to most hooks. The value returned by this
+   callback must be returned by the hook function unless otherwise specified.
 
 ## Return values
-A hook should always return a list or undefined. Returning undefined is equivalent to returning an empty list.
-All the returned lists are appended to each other, so if the return values where `[1, 2]`, `undefined`, `[3, 4,]`, `undefined` and `[5]`, the value returned by callHook would be `[1, 2, 3, 4, 5]`.
 
-This is, because it should never matter if you have one plugin or several plugins doing some work - a single plugin should be able to make callHook return the same value a set of plugins are able to return collectively. So, any plugin can return a list of values, of any length, not just one value.
+Note: This section applies to every hook unless the hook-specific documentation
+says otherwise.
+
+Hook functions return zero or more values to Etherpad by passing an array to the
+provided callback. Hook functions typically provide a single value (array of
+length one). If the function does not want to or need to provide a value, it may
+pass an empty array or `undefined` (which is treated the same as an empty
+array). Hook functions may also provide more than one value (array of length two
+or more).
+
+Some hooks concatenate the arrays provided by its registered functions. For
+example, if a hook's registered functions pass `[1, 2]`, `undefined`, `[3, 4]`,
+`[]`, and `[5]` to the provided callback, then the hook's return value is `[1,
+2, 3, 4, 5]`.
+
+Other hooks only use the first non-empty array provided by a registered
+function. In this case, each of the hook's registered functions is called one at
+a time until one provides a non-empty array. The remaining functions are
+skipped. If none of the functions provide a non-empty array, or there are no
+registered functions, the hook's return value is `[]`.
+
+Example:
+
+```
+exports.abstractHook = (hookName, context, callback) => {
+  if (notApplicableToThisPlugin(context)) {
+    return callback();
+  }
+  const value = doSomeProcessing(context);
+  return callback([value]);
+};
+```