Document IRC::Client methods

2 files changed, 213 insertions, 1 deletions

diff --git a/docs/03-method-reference.md b/docs/03-method-reference.md
index 85e86e4..9221474 100644
--- a/docs/03-method-reference.md
+++ b/docs/03-method-reference.md
@@ -413,6 +413,215 @@ the socket connected to the server, although it may already be closed.
 ---
 
 ## Client Object (`IRC::Client`)
+
+The Client Object is the heart of this module. The `IRC::Client` you instantiate
+and `.run`. The running Client Object is available to your plugins via
+`.irc` attribute that you can obtain by doing the `IRC::Client::Plugin` role
+or via `.irc` attribute on Message Objects your event handler receives.
+
+The client object's method let you control the client: e.g. joining or parting
+channels, changing nicks, banning users, or sending text messages.
+
+### Methods and Attributes
+
+#### `.join`
+
+```perl6
+    $.irc.join: <#foo #bar #ber>, :$server;
+```
+
+Causes the client join the provided channels.
+If `:server` named argument is given, will operate only on that server;
+otherwise operates on all connected servers.
+
+#### `.new`
+
+```perl6
+my $irc = IRC::Client.new:
+    :debug
+    :host<irc.freenode.net>
+    :6667port
+    :password<s3cret>
+    :channels<#perl #perl6 #rust-lang>
+    :nick<MahBot>
+    :username<MahBot>
+    :userhost<localhost>
+    :userreal('Mah awesome bot!')
+    :servers(
+        freenode => %(),
+        local    => %( :host<localhost> ),
+    )
+    :plugins(
+        class { method irc-to-me ($ where /42/) { 'The answer to universe!' } }
+    )
+    :filters(
+        -> $text where .lines > 5 or .chars > 300 { "Text is too big!!!" }
+    )
+```
+
+Instantiates a new `IRC::Client` object. Takes the following named arguments:
+
+##### `:channels`
+
+A list of IRC channels to join. **Defaults to:** `#perl6`
+
+##### `:debug`
+
+Takes an `Int`. When set to a positive number, causes debug output to be
+generated. Install optional
+[Terminal::ANSIColor]https://modules.perl6.org/repo/Terminal::ANSIColor] to
+make output colourful. Debug levels:
+
+* `0`—no debug output
+* `1`—basic debug output
+* `2`—also include list of emitted events
+* `3`—also include `irc-all` in the list of emitted events
+
+**Defaults to:** `0`
+
+##### `:filters`
+
+Takes a list of `Callable`s. Will attempt to call them for replies to
+`PRIVMSG` and `NOTICE` events if the signatures accept `($text)` or
+`($text, :$where)` calls, where `$text` is the reply text and `:$where` is
+a named argument of the destination of the reply (either a user or a channel
+name).
+
+Callables with `:$where` in the signature must return two values: the new
+text to reply with and the location. Otherwise, just one value needs to
+be returned: the new text to reply with.
+
+**By default** not specified.
+
+##### `:host`
+
+The hostname of the IRC server to connect to.
+**Defaults to:** `localhost`
+
+##### `:nick`
+
+A list of nicknames to use. If set to just one value will automatically
+generate three additional nicknames that have underscores appended
+(e.g. `P6Bot`, `P6Bot_`, `P6Bot__`, `P6Bot___`).
+
+If one of the given nicks is in use, the client will attempt to use the
+next one in the list.
+
+**Defaults to:** `P6Bot`
+
+##### `:password`
+
+The server password to use. On some networks (like Freenode), the server
+password also functions as NickServ's password.
+**By default** not specified.
+
+##### `:plugins`
+
+Takes a list of instantiated objects or type objects that implement the
+functionality of the system. See [basics tutorial](01-basics.md) and
+[event reference](02-event-reference.md) for more information on how
+to implement plugin classes.
+
+**By default** not specified.
+
+##### `:port`
+
+The port of the IRC server to connect to. Takes an `Int` between 0 and 65535.
+**Defaults to:** `6667`
+
+##### `:servers`
+
+Takes an `Assosiative` with keys as labels of servers and values with
+server-specific configuration. Valid keys in the configuration are
+`:host`, `:port`, `:password`, `:channels`, `:nick`, `:username`,
+`:userhost`, and `:userreal`. They take the same values as same-named arguments
+of the `IRC::Client.new` method and if any key is omitted, the value
+of the `.new`'s argument will be used.
+
+##### `:username`
+
+The IRC username to use. **Defaults to:** `Perl6IRC`
+
+##### `:userhost`
+
+The hostname of your client. **Defaults to:** `localhost` and can probably
+be left as is, unless you're having issues connecting.
+
+##### `:userreal`
+
+The "real name" of your client. **Defaults to:** `Perl6 IRC Client`
+
+----
+
+#### `.nick`
+
+```perl6
+    $.irc.nick: 'MahBot', :$server;
+    $.irc.nick: <MahBot MahBot2 MahBot3 MahBot4 MahBot5>, :$server;
+```
+
+Causes the client to change its nick to the one provided and uses this
+as new value of `.current-nick` and `.nick` attributes of the appropriate
+`IRC::Client::Server` object. If only one nick
+is given, another 3 nicks will be automatically generated by appending
+a number of underscores. Will automatically retry nicks further in the list
+if the currently attempted one is already in use.
+
+If `:server` named argument is given, will operate only on that server;
+ otherwise operates on all connected servers.
+
+#### `.part`
+
+```perl6
+    $.irc.part: <#foo #bar #ber>, :$server;
+```
+
+Causes the client part the provided channels.
+If `:server` named argument is given, will operate only on that server;
+otherwise operates on all connected servers.
+
+#### `.quit`
+
+```perl6
+    $.irc.quit;
+    $.irc.quit: :$server;
+```
+
+Causes the client to quit the IRC server.
+If `:server` named argument is given, will operate only on that server;
+otherwise operates on all connected servers.
+
+#### `.run`
+
+Takes no arguments. Runs the IRC client, causing it to connect to servers
+and do all of its stuff. Returns only if all of the servers the client connects
+to have been explicitly `.quit` from.
+
+#### `.send`
+
+```perl6
+    $.irc.send: :where<Zoffix> :text<Hello!>;
+    $.irc.send: :where<#perl6> :text('I ♥ Perl 6!');
+    $.irc.send: :where<Senpai> :text('Notice me!') :notice :$server;
+```
+
+Sends a `:text` message to `:where`, using either a `PRIVMSG` or `NOTICE`.
+The `:where` can be either a user's nick or a channel name. If `:notice`
+argument is set to a `True` value will use `NOTICE` otherwise will use
+`PRIVMSG` (if you just want to send text to channel like you'd normally
+do when talking with regular IRC clients, that'd be the `PRIVMSG` messages).
+
+If `:server` named argument is given, will operate only on that server;
+otherwise operates on all connected servers.
+
+**NOTE:** calls to `.send` when server is not connected yet will be
+**semi-silently ignored** (only debug output will mention that they were
+ignored). This is done on purpose, to prevent `.send` calls from interfering
+with the connection negotiation during server reconnects. Although not
+free from race conditions, you can mitigate this issue by checking the
+`.is-connected` attribute on the appropriate `IRC::Client::Server` object
+before attempting the `.send`
+
 ## Up Next
 
-Read [the method reference](03-method-reference.md) next.
+Read [Big Picture behaviour](04-big-picture-behaviour) next.
diff --git a/docs/04-big-picture-behaviour.md b/docs/04-big-picture-behaviour.md
new file mode 100644
index 0000000..17513c4
--- /dev/null
+++ b/docs/04-big-picture-behaviour.md
@@ -0,0 +1,3 @@
+[[back to main docs]](../README.md#documentation-map)
+
+# Big-Picture Behaviour