Implement MotdFinished, improve some docs

CHANGELOG

 vNEXT (in development)
 
+ * Added MotdFinished event
+ * Improved some documentation
+
 v0.4.0
 
  * Added CtcpReceived and ActionReceived events

README.md

 with(IrcClientImpl(Server("my.server.com", 6667), Profile("nick", "realName", "userName"))) {
     onEvent { event ->
         when (event) {
-            is ServerWelcome -> sendJoin("#ktirc")
+            is ServerReady -> sendJoin("#ktirc")
             is MessageReceived ->
                 if (event.message == "!test")
                     reply(event, "Test successful!")

src/main/kotlin/com/dmdirc/ktirc/IrcClient.kt

      * Sends the given raw line to the IRC server, followed by a carriage return and line feed.
      *
      * Standard IRC messages can be constructed using the methods in [com.dmdirc.ktirc.messages]
-     * such as [joinMessage].
+     * such as [sendJoin].
      *
      * @param message The line to be sent to the IRC server.
      */
     /**
      * Registers a new handler for all events on this connection.
      *
-     * All events are subclasses of [IrcEvent]; the idomatic way to handle them is using a `when` statement:
+     * All events are subclasses of [IrcEvent]; the idiomatic way to handle them is using a `when` statement:
      *
      * ```
      * client.onEvent {
 
                 connect()
 
-                with (Channel<ByteArray>(Channel.UNLIMITED)) {
+                with(Channel<ByteArray>(Channel.UNLIMITED)) {
                     writeChannel = this
-                    scope.launch { writeLines(this@with) }
+                    scope.launch {
+                        writeChannel?.let {
+                            writeLines(it)
+                        }
+                    }
                 }
 
                 emitEvent(ServerConnected(currentTimeProvider()))

src/main/kotlin/com/dmdirc/ktirc/events/Events.kt

 
 /** Raised when the server has finished sending us capabilities. */
 class ServerCapabilitiesFinished(time: LocalDateTime) : IrcEvent(time)
+
+/** Raised when a Message Of the Day has completed. */
+class MotdFinished(time: LocalDateTime, val missing: Boolean = false): IrcEvent(time)

src/main/kotlin/com/dmdirc/ktirc/messages/MessageProcessor.kt

         CapabilityProcessor(),
         ISupportProcessor(),
         JoinProcessor(),
+        MotdProcessor(),
         NamesProcessor(),
         PartProcessor(),
         PingProcessor(),

src/main/kotlin/com/dmdirc/ktirc/messages/MotdProcessor.kt

+package com.dmdirc.ktirc.messages
+
+import com.dmdirc.ktirc.events.MotdFinished
+import com.dmdirc.ktirc.model.IrcMessage
+
+internal class MotdProcessor : MessageProcessor {
+
+    override val commands = arrayOf("422", "376")
+
+    override fun process(message: IrcMessage) = sequence {
+        when (message.command) {
+            "422" -> yield(MotdFinished(message.time, missing = true))
+            "376" -> yield(MotdFinished(message.time))
+        }
+    }.toList()
+
+}

src/main/kotlin/com/dmdirc/ktirc/model/ServerState.kt

     var status = ServerStatus.Connecting
         internal set
 
-    /** Our present nickname on the server. */
+    /**
+     * What we believe our current nickname to be on the server.
+     *
+     * Initially this will be the nickname provided in the [Profile]. It will be updated to the actual nickname
+     * in use when connecting. Once you have received a [com.dmdirc.ktirc.events.ServerWelcome] event you can
+     * rely on this value being current.
+     * */
     var localNickname: String = initialNickname
         internal set
 
-    /** The server's name, as reported by it. */
+    /**
+     * The name of the server we are connected to.
+     *
+     * Initially this will be the hostname or IP address provided in the [Server]. It will be updated to the server's
+     * self-reported hostname when connecting. Once you have received a [com.dmdirc.ktirc.events.ServerWelcome] event
+     * you can rely on this value being current.
+     */
     var serverName: String = initialServerName
         internal set
 

src/test/kotlin/com/dmdirc/ktirc/messages/MotdProcessorTest.kt

+package com.dmdirc.ktirc.messages
+
+import com.dmdirc.ktirc.TestConstants
+import com.dmdirc.ktirc.events.MotdFinished
+import com.dmdirc.ktirc.model.IrcMessage
+import com.dmdirc.ktirc.util.currentTimeProvider
+import org.junit.jupiter.api.Assertions.*
+import org.junit.jupiter.api.BeforeEach
+import org.junit.jupiter.api.Test
+
+internal class MotdProcessorTest {
+
+    @BeforeEach
+    fun setUp() {
+        currentTimeProvider = { TestConstants.time }
+    }
+
+    @Test
+    fun `MotdProcessor raises motdFinished when not found numeric received`() {
+        val events = MotdProcessor().process(
+                IrcMessage(emptyMap(), "the.gibson".toByteArray(), "422", listOf("MOTD missing".toByteArray())))
+        assertEquals(1, events.size)
+
+        val event = events[0] as MotdFinished
+        assertEquals(TestConstants.time, events[0].time)
+        assertTrue(event.missing)
+    }
+
+    @Test
+    fun `MotdProcessor raises motdFinished when MOTD finishes normally`() {
+        val events = MotdProcessor().process(
+                IrcMessage(emptyMap(), "the.gibson".toByteArray(), "376", listOf("acidBurn".toByteArray(), "End of /MOTD command.".toByteArray())))
+        assertEquals(1, events.size)
+
+        val event = events[0] as MotdFinished
+        assertEquals(TestConstants.time, events[0].time)
+        assertFalse(event.missing)
+    }
+
+}