Document IrcClient, make lots of things internal.

CHANGELOG

@@ -1,5 +1,6 @@
 vNEXT (in development)
 
+  * Added documentation and reduced visibility of some internal methods/classes
   * (Internal) Enabled Travis, Codacy and Coveralls
 
 v0.2.0

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

@@ -10,30 +10,79 @@ import java.util.concurrent.atomic.AtomicBoolean
 import java.util.logging.Level
 import java.util.logging.LogManager
 
-
+/**
+ * Primary interface for interacting with KtIrc.
+ */
 interface IrcClient {
 
-    fun send(message: String)
-
     val serverState: ServerState
     val channelState: ChannelStateMap
     val userState: UserState
 
-    fun onEvent(handler: (IrcEvent) -> Unit)
-
     val caseMapping: CaseMapping
         get() = serverState.features[ServerFeature.ServerCaseMapping] ?: CaseMapping.Rfc
 
-    fun isLocalUser(user: User): Boolean = caseMapping.areEquivalent(user.nickname, serverState.localNickname)
+    /**
+     * Begins a connection attempt to the IRC server.
+     *
+     * This method will return immediately, and the attempt to connect will be executed in a coroutine on the
+     * IO scheduler. To check the status of the connection, monitor events using [onEvent].
+     */
+    fun connect()
+
+    /**
+     * Disconnect immediately from the IRC server, without sending a QUIT.
+     */
+    fun disconnect()
+
+    /**
+     * 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].
+     *
+     * @param message The line to be sent to the IRC server.
+     */
+    fun send(message: String)
+
+    /**
+     * 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:
+     *
+     * ```
+     * client.onEvent {
+     *     when(it) {
+     *         is MessageReceived -> println(it.message)
+     *     }
+     * }
+     * ```
+     *
+     * *Note*: at present handlers cannot be removed; they last the lifetime of the [IrcClient].
+     *
+     * @param handler The method to call when a new event occurs.
+     */
+    fun onEvent(handler: (IrcEvent) -> Unit)
+
+    /**
+     * Utility method to determine if the given user is the one we are connected to IRC as.
+     */
+    fun isLocalUser(user: User) = caseMapping.areEquivalent(user.nickname, serverState.localNickname)
 
 }
 
+/**
+ * Concrete implementation of an [IrcClient].
+ *
+ * @param server The server to connect to.
+ * @param profile The user details to use when connecting.
+ */
 // TODO: How should alternative nicknames work?
 // TODO: Should IRC Client take a pool of servers and rotate through, or make the caller do that?
 // TODO: Should there be a default profile?
 class IrcClientImpl(private val server: Server, private val profile: Profile) : IrcClient {
 
-    var socketFactory: (String, Int, Boolean) -> LineBufferedSocket = ::KtorLineBufferedSocket
+    internal var socketFactory: (String, Int, Boolean) -> LineBufferedSocket = ::KtorLineBufferedSocket
 
     override val serverState = ServerState(profile.initialNick)
     override val channelState = ChannelStateMap { caseMapping }
@@ -55,7 +104,7 @@ class IrcClientImpl(private val server: Server, private val profile: Profile) :
         }
     }
 
-    fun connect() {
+    override fun connect() {
         check(!connecting.getAndSet(true))
         connectionJob = scope.launch {
             with(socketFactory(server.host, server.port, server.tls)) {
@@ -72,7 +121,7 @@ class IrcClientImpl(private val server: Server, private val profile: Profile) :
         }
     }
 
-    fun disconnect() {
+    override fun disconnect() {
         socket?.disconnect()
     }
 
@@ -89,7 +138,7 @@ class IrcClientImpl(private val server: Server, private val profile: Profile) :
     }
 }
 
-fun main() {
+internal fun main() {
     val rootLogger = LogManager.getLogManager().getLogger("")
     rootLogger.level = Level.FINEST
     for (h in rootLogger.handlers) {
@@ -109,4 +158,4 @@ fun main() {
         client.connect()
         client.join()
     }
-}
+}

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

@@ -8,7 +8,7 @@ import com.dmdirc.ktirc.model.CapabilitiesState
 import com.dmdirc.ktirc.model.Capability
 import com.dmdirc.ktirc.util.logger
 
-class CapabilitiesHandler : EventHandler {
+internal class CapabilitiesHandler : EventHandler {
 
     private val log by logger()
 

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

@@ -5,7 +5,7 @@ import com.dmdirc.ktirc.model.ChannelState
 import com.dmdirc.ktirc.model.ChannelUser
 import com.dmdirc.ktirc.util.logger
 
-class ChannelStateHandler : EventHandler {
+internal class ChannelStateHandler : EventHandler {
 
     private val log by logger()
 

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

@@ -3,13 +3,13 @@ package com.dmdirc.ktirc.events
 import com.dmdirc.ktirc.IrcClient
 
 @FunctionalInterface
-interface EventHandler {
+internal interface EventHandler {
 
     fun processEvent(client: IrcClient, event: IrcEvent)
 
 }
 
-val eventHandlers = listOf(
+internal val eventHandlers = listOf(
         CapabilitiesHandler(),
         ChannelStateHandler(),
         PingHandler(),

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

@@ -4,7 +4,7 @@ import com.dmdirc.ktirc.IrcClient
 import com.dmdirc.ktirc.model.ServerFeature
 import com.dmdirc.ktirc.model.asUser
 
-fun ChannelNamesReceived.toModesAndUsers(client: IrcClient) = sequence {
+internal fun ChannelNamesReceived.toModesAndUsers(client: IrcClient) = sequence {
     val modePrefixes = client.serverState.features[ServerFeature.ModePrefixes]!!
     for (user in names) {
         user.takeWhile { modePrefixes.isPrefix(it) }.let { prefix ->

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

@@ -3,7 +3,7 @@ package com.dmdirc.ktirc.events
 import com.dmdirc.ktirc.IrcClient
 import com.dmdirc.ktirc.messages.pongMessage
 
-class PingHandler : EventHandler {
+internal class PingHandler : EventHandler {
 
     override fun processEvent(client: IrcClient, event: IrcEvent) {
         when (event) {

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

@@ -2,7 +2,7 @@ package com.dmdirc.ktirc.events
 
 import com.dmdirc.ktirc.IrcClient
 
-class ServerStateHandler : EventHandler {
+internal class ServerStateHandler : EventHandler {
 
     override fun processEvent(client: IrcClient, event: IrcEvent) {
         when (event) {

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

@@ -3,7 +3,7 @@ package com.dmdirc.ktirc.events
 import com.dmdirc.ktirc.IrcClient
 import com.dmdirc.ktirc.model.UserState
 
-class UserStateHandler : EventHandler {
+internal class UserStateHandler : EventHandler {
 
     override fun processEvent(client: IrcClient, event: IrcEvent) {
         when (event) {

src/main/kotlin/com/dmdirc/ktirc/io/CaseMapping.kt

@@ -7,7 +7,7 @@ enum class CaseMapping(private val lowerToUpperMapping: Pair<IntRange, IntRange>
     RfcStrict(97..125 to 65..93);
 
     companion object {
-        fun fromName(name: String) = when(name.toLowerCase()) {
+        internal fun fromName(name: String) = when(name.toLowerCase()) {
             "ascii" -> Ascii
             "rfc1459" -> Rfc
             "rfc1459-strict" -> RfcStrict

src/main/kotlin/com/dmdirc/ktirc/io/LineBufferedSocket.kt

@@ -19,7 +19,7 @@ import java.net.InetSocketAddress
 import java.security.SecureRandom
 import javax.net.ssl.X509TrustManager
 
-interface LineBufferedSocket {
+internal interface LineBufferedSocket {
 
     suspend fun connect()
     fun disconnect()
@@ -35,7 +35,7 @@ interface LineBufferedSocket {
  * Asynchronous socket that buffers incoming data and emits individual lines.
  */
 // TODO: Expose advanced TLS options
-class KtorLineBufferedSocket(private val host: String, private val port: Int, private val tls: Boolean = false): LineBufferedSocket {
+internal class KtorLineBufferedSocket(private val host: String, private val port: Int, private val tls: Boolean = false): LineBufferedSocket {
 
     companion object {
         const val CARRIAGE_RETURN = '\r'.toByte()

src/main/kotlin/com/dmdirc/ktirc/io/MessageHandler.kt

@@ -8,7 +8,7 @@ import com.dmdirc.ktirc.util.logger
 import kotlinx.coroutines.channels.ReceiveChannel
 import kotlinx.coroutines.channels.consumeEach
 
-class MessageHandler(private val processors: List<MessageProcessor>, val handlers: MutableList<EventHandler>) {
+internal class MessageHandler(private val processors: List<MessageProcessor>, val handlers: MutableList<EventHandler>) {
 
     private val log by logger()
 

src/main/kotlin/com/dmdirc/ktirc/io/MessageParser.kt

@@ -17,17 +17,21 @@ import com.dmdirc.ktirc.util.logger
  *
  * For example:
  *
+ * ```
  * @aaa=bbb;ccc;example.com/ddd=eee :nick!ident@host.com PRIVMSG #someChannel :This is a test message
  * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^ ^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
  * IRCv3 tags                       Prefix               Cmd     Param #1     Trailing parameter
+ * ```
  *
  * or:
  *
+ * ```
  * PING 12345678
  * ^^^^ ^^^^^^^^
  * Cmd  Param #1
+ * ```
  */
-class MessageParser {
+internal class MessageParser {
 
     companion object {
         private const val AT = '@'.toByte()

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

@@ -8,7 +8,7 @@ import com.dmdirc.ktirc.model.capabilities
 import com.dmdirc.ktirc.util.logger
 import java.time.LocalDateTime
 
-class CapabilityProcessor : MessageProcessor {
+internal class CapabilityProcessor : MessageProcessor {
 
     private val log by logger()
 

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

@@ -3,7 +3,7 @@ package com.dmdirc.ktirc.messages
 import com.dmdirc.ktirc.events.IrcEvent
 import com.dmdirc.ktirc.model.IrcMessage
 
-interface MessageProcessor {
+internal interface MessageProcessor {
 
     /**
      * The messages which this handler can process.
@@ -17,7 +17,7 @@ interface MessageProcessor {
 
 }
 
-val messageProcessors = setOf(
+internal val messageProcessors = setOf(
         CapabilityProcessor(),
         ISupportProcessor(),
         JoinProcessor(),

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

@@ -35,6 +35,6 @@ sealed class Capability(val name: String) {
     object HostChangeMessages : Capability("chghost") // TODO: Add processor
 }
 
-val capabilities: Map<String, Capability> by lazy {
+internal val capabilities: Map<String, Capability> by lazy {
     Capability::class.nestedClasses.map { it.objectInstance as Capability }.associateBy { it.name }
 }

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

@@ -30,6 +30,6 @@ sealed class MessageTag(val name: String) {
     object ServerTime : MessageTag("time")
 }
 
-val messageTags: Map<String, MessageTag> by lazy {
+internal val messageTags: Map<String, MessageTag> by lazy {
     MessageTag::class.nestedClasses.map { it.objectInstance as MessageTag }.associateBy { it.name }
 }

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

@@ -45,6 +45,6 @@ sealed class ServerFeature<T : Any>(val name: String, val type: KClass<T>, val d
     object WhoxSupport : ServerFeature<Boolean>("WHOX", Boolean::class, false)
 }
 
-val serverFeatures: Map<String, ServerFeature<*>> by lazy {
+internal val serverFeatures: Map<String, ServerFeature<*>> by lazy {
     ServerFeature::class.nestedClasses.map { it.objectInstance as ServerFeature<*> }.associateBy { it.name }
 }

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

@@ -18,9 +18,9 @@ data class User(
     }
 }
 
-fun ByteArray.asUser() = String(this).asUser()
+internal fun ByteArray.asUser() = String(this).asUser()
 
-fun String.asUser(): User {
+internal fun String.asUser(): User {
     val identOffset = indexOf('!')
     return if (identOffset >= 0) {
         val hostOffset = indexOf('@', identOffset)

src/main/kotlin/com/dmdirc/ktirc/util/Logging.kt

@@ -7,6 +7,6 @@ private fun <T: Any> logger(forClass: KClass<T>): Logger {
     return Logger.getLogger(forClass.qualifiedName)
 }
 
-fun <R : Any> R.logger(): Lazy<Logger> {
+internal fun <R : Any> R.logger(): Lazy<Logger> {
     return lazy { logger(this::class) }
 }