From cf80b1b4392b849cb5529c1a40083170098f6460 Mon Sep 17 00:00:00 2001
From: Zoffix Znet <cpan@zoffix.com>
Date: Thu, 28 Jul 2016 22:52:25 -0400
Subject: Docs

---
 docs/02-event-reference.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 docs/02-event-reference.md

(limited to 'docs/02-event-reference.md')

diff --git a/docs/02-event-reference.md b/docs/02-event-reference.md
new file mode 100644
index 0000000..e42a659
--- /dev/null
+++ b/docs/02-event-reference.md
@@ -0,0 +1,48 @@
+[[back to main docs]](../README.md#documentation-map)
+
+# Event Reference
+
+The module offers named, numeric, and convenience events. The named and
+numeric events correspond to IRC protocol events, while convenience events
+are an extra layer provided to make using the module easier. This means one
+IRC event can trigger several events of the module. For example, if someone
+addresses our bot in a channel, the following chain of events will be fired:
+
+    irc-addressed  ▶  irc-to-me  ▶  irc-privmsg-channel  ▶  irc-privmsg  ▶  irc-all
+
+The events are ordered from "narrowest" to "widest": `irc-addressed` can be
+triggered only in-channel, when our bot is addressed; `irc-to-me` can also
+be triggered via notice and private message, so it's wider;
+`irc-privmsg-channel` includes all channel messages, so it's wider still;
+and `irc-privmsg` also includes private messages to our bot. The chain ends
+by the widest event of them all: `irc-all`.
+
+## Event Map
+
+All event chains end with `irc-all`, which is not shown in the table below,
+for brevity. `irc-XXX` stands for numeric events where `XXX` is a
+three-digit number. See [this numerics
+table](https://www.alien.net.au/irc/irc2numerics.html) for meaning of codes,
+depending on the server used.
+
+```
+irc-addressed  ▶  irc-to-me      ▶  irc-privmsg-channel  ▶  irc-privmsg
+                  irc-mentioned  ▶  irc-privmsg-channel  ▶  irc-privmsg
+                                    irc-privmsg-channel  ▶  irc-privmsg
+                  irc-to-me      ▶  irc-privmsg-me       ▶  irc-privmsg
+
+irc-addressed  ▶  irc-to-me      ▶  irc-notice-channel   ▶  irc-notice
+                  irc-mentioned  ▶  irc-notice-channel   ▶  irc-notice
+                                    irc-notice-channel   ▶  irc-notice
+                  irc-to-me      ▶  irc-notice-me        ▶  irc-notice
+
+                                    irc-mode-channel     ▶  irc-mode
+                                    irc-mode-me          ▶  irc-mode
+
+                  irc-connected  ▶  irc-numeric          ▶  irc-XXX
+                                    irc-numeric          ▶  irc-XXX
+```
+
+## Up Next
+
+Read [the method reference](03-method-reference.md) next.
-- 
cgit v1.1