From 311095fd68090ed82e9fff9f71003bc5247a108b Mon Sep 17 00:00:00 2001
From: Zoffix Znet <cpan@zoffix.com>
Date: Thu, 28 Jul 2016 23:14:23 -0400
Subject: Document irc-started caveats

---
 docs/01-basics.md          |  2 +-
 docs/02-event-reference.md | 12 ++++++++++++
 lib/IRC/Client.pm6         |  3 +--
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/docs/01-basics.md b/docs/01-basics.md
index 36ae32f..bbbdcd0 100644
--- a/docs/01-basics.md
+++ b/docs/01-basics.md
@@ -104,7 +104,7 @@ the `$.irc` attribute:
 use IRC::Client;
 
 class AlarmBot does IRC::Client::Plugin {
-    method irc-connected ($) {
+    method irc-started {
         react {
             whenever Supply.interval(3) {
                 $.irc.send: :where<#perl6> :text<Three seconds passed!>;
diff --git a/docs/02-event-reference.md b/docs/02-event-reference.md
index f2bed7b..d990307 100644
--- a/docs/02-event-reference.md
+++ b/docs/02-event-reference.md
@@ -55,6 +55,18 @@ irc-addressed  ▶  irc-to-me      ▶  irc-notice-channel   ▶  irc-notice   
                                                                             irc-started
 ```
 
+**Note:** `irc-started` is a special event that's exempt from the rules
+applicable to all other events and their event handlers:
+
+* It's called just once per call of `IRC::Client`'s `.run` method, regardless
+of how many times the client reconnects
+* When it's called, there's no guarantee the connections to servers have
+been fully established yet or channels joined yet.
+* Unless all other event handlers, this one does not take any arguments
+* Return values from handlers are ignored and the event is propagated to all of
+the plugins
+* This event does not trigger `irc-all` event
+
 ## Up Next
 
 Read [the method reference](03-method-reference.md) next.
diff --git a/lib/IRC/Client.pm6 b/lib/IRC/Client.pm6
index adc885b..863b50f 100644
--- a/lib/IRC/Client.pm6
+++ b/lib/IRC/Client.pm6
@@ -81,8 +81,6 @@ method part (*@channels, :$server) {
 
 method run {
     .irc = self for @.plugins.grep: { .DEFINITE and .^can: 'irc' };
-    .irc-started for self!plugs-that-can('irc-started', $e);
-
     start {
         my $closed = $!event-pipe.closed;
         loop {
@@ -99,6 +97,7 @@ method run {
     }
 
     self!connect-socket: $_ for %!servers.values;
+    .irc-started for self!plugs-that-can('irc-started', $e);
     loop {
         my $s = $!socket-pipe.receive;
         self!connect-socket: $s unless $s.has-quit;
-- 
cgit v1.1