WIP

doc/developers-guide/hooks_description.md

@@ -137,39 +137,48 @@ These hooks are handled by the following modules:
 ## `offline_message_hook`
 
 ```erlang
-mongoose_hooks:offline_message_hook(Acc, From, To, Packet);
+mongoose_hooks:offline_message_hook(Acc, From, To, Packet)
 ```
 
-`ejabberd_sm` runs this hook once it determines that a routed stanza is a message and while it ordinarily could be delivered, no resource (i.e. device or desktop client application) of its recipient is available online for delivery.
+`ejabberd_sm` runs this hook for each message which cannot be delivered, because no resource (i.e. device or desktop client application) of its recipient is available online for delivery.
 
-The following depends on configuration, but the hook is first handled by `mod_offline_chatmarkers`, which filters out and chat marker packets processed by `mod_smart_markers`.
-The handler stores such messages and returns `{stop, Acc}`, which terminates the call and no more hook handlers are called.
-In case of other packets, `mod_offline` should store the message in a persistent way until the recipient comes online, and the message can be successfully delivered.
-Similarly, it stops the other hooks from running after that.
+### Handler examples
+
+This hook is handled by the following modules, listed in the order of execution:
+
+* [`mod_offline_chatmarkers`](../modules/mod_offline_chatmarkers.md) - for chat marker messages, the handler stores them and returns `{stop, Acc}`, preventing further handlers from being called. Such messages are then processed by `mod_smart_markers`.
+
+* [`mod_offline`](../modules/mod_offline.md) - stores messages in a persistent way until the recipient comes online, and the message can be successfully delivered. The handler returns `{stop, Acc}` for all messages, preventing further handlers from being called.
 
-If the `mod_offline` handler fails to store the message, we should notify the user that the message could not be stored.
-To this end, there is another handler registered, but with a greater sequence number, so that it is called after `mod_offline`.
-If `mod_offline` fails, `ejabberd_sm:bounce_offline_message` is called, and the user gets their notification.
+* [`mod_offline_stub`](../modules/mod_offline_stub.md) - returns `{stop, Acc}` for all messages, preventing further handlers from being called.
 
-In the case of using `mod_mam` the message is actually stored and no notification should be sent - that's why the module `mod_offline_stub` can be enabled.
-It can handle the hook before `ejabberd_sm`, preventing it from sending `<service-unavailable/>`.
+* `ejabberd_sm` - calls `ejabberd_sm:bounce_offline_message`, which responds with the `<service-unavailable/>` stanza error. In the case of using `mod_mam` the message is actually stored, and no such error should be sent - that's why the module `mod_offline_stub` can be enabled.
 
 ## `remove_user`
 
 ```erlang
-mongoose_hooks:remove_user(LServer, Acc, LUser)
+mongoose_hooks:remove_user(Acc, LServer, LUser)
 ```
 
 `remove_user` is run by `ejabberd_auth` - the authentication module - when a request is made to remove the user from the database of the server.
-This one is rather complex, since removing a user requires many cleanup operations:
-`mod_last` removes last activity information ([XEP-0012: Last Activity][XEP-0012]);
-`mod_mam` removes the user's message archive;
-`mod_muc_light` quits multi-user chat rooms;
-`mod_offline` deletes the user's offline messages;
-`mod_privacy` removes the user's privacy lists;
-`mod_private` removes the user's private xml data storage;
-`mod_pubsub` unsubscribes from publish/subscribe channels;
-and `mod_roster` removes the user's roster from the database.
+
+### Handler examples
+
+This hook is used by multiple modules, since removing a user requires many cleanup operations:
+
+* [`mod_auth_token`](../modules/mod_auth_token.md) removes user's authentication tokens;
+* [`mod_event_pusher`](../modules/mod_event_pusher.md) disables user's push notifications;
+* [`mod_inbox`](../modules/mod_inbox.md) removes user's inbox;
+* [`mod_last`](../modules/mod_smart_markers.md) removes last activity information ([XEP-0012: Last Activity][XEP-0012]);
+* [`mod_mam`](../modules/mod_mam.md) removes the user's message archive;
+* [`mod_muc_light`](../modules/mod_muc_light.md) quits multi-user chat rooms;
+* [`mod_offline`](../modules/mod_offline.md) deletes the user's offline messages;
+* [`mod_privacy`](../modules/mod_privacy.md) removes the user's privacy lists;
+* [`mod_private`](../modules/mod_private.md) removes the user's private xml data storage;
+* [`mod_pubsub`](../modules/mod_pubsub.md) unsubscribes from publish/subscribe channels;
+* [`mod_roster`](../modules/mod_roster.md) removes the user's roster from the database;
+* [`mod_smart_markers`](../modules/mod_smart_markers.md) removes chat markers stored for the user;
+* [`mod_vcard`](../modules/mod_vcard.md) removes user's vCard information.
 
 ## `node_cleanup`
 
@@ -189,7 +198,7 @@ Setting retries to 0 is not good decision as it was observed that in some setups
 
 ## `session_opening_allowed_for_user`
 ```erlang
-allow == mongoose_hooks:session_opening_allowed_for_user(HostType, JID).
+allow == mongoose_hooks:session_opening_allowed_for_user(HostType, JID)
 ```
 
 This hook is run after authenticating when user sends the IQ opening a session.