Documentation

CHANGELOG

@@ -1,5 +1,7 @@
 vNEXT (in development)
 
+  * Added more documentation to public methods/classes
+
 v0.3.0
 
   * Simplified how messages are constructed.

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

@@ -1,9 +1,15 @@
 package com.dmdirc.ktirc.io
 
+/**
+ * Supported options for mapping between uppercase and lowercase characters.
+ */
 enum class CaseMapping(private val lowerToUpperMapping: Pair<IntRange, IntRange>) {
 
+    /** Standard ASCII mapping, `a-z` is mapped to `A-Z`. */
     Ascii(97..122 to 65..90),
+    /** Mapping probably intended by RFC14159, `a-z{|}~` is mapped to `A-Z[\]^`. */
     Rfc(97..126 to 65..94),
+    /** Mapping according to a strict interpretation of RFC14159, `a-z{|}` is mapped to `A-Z[\]]`. */
     RfcStrict(97..125 to 65..93);
 
     companion object {
@@ -15,6 +21,9 @@ enum class CaseMapping(private val lowerToUpperMapping: Pair<IntRange, IntRange>
         }
     }
 
+    /**
+     * Determines if the two strings are equivalent under the casemapping rules.
+     */
     fun areEquivalent(string1: String, string2: String): Boolean {
         return string1.length == string2.length
                 && string1.zip(string2).all { (c1, c2) -> areEquivalent(c1, c2) }

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

@@ -1,38 +1,75 @@
 package com.dmdirc.ktirc.model
 
+/**
+ * Describes the state of capability negotiation with the server.
+ */
 class CapabilitiesState {
 
+    /** The current negotiation state. */
     var negotiationState: CapabilitiesNegotiationState = CapabilitiesNegotiationState.AWAITING_LIST
+        internal set
 
+    // TODO: These should only be mutable internally
+    /** The capabilities that were advertised by the server. */
     val advertisedCapabilities = HashMap<Capability, String>()
+    /** The capabilities that we have agreed to enable. */
     val enabledCapabilities = HashMap<Capability, String>()
 
 }
 
+/**
+ * The state of negotiations with the server.
+ */
 enum class CapabilitiesNegotiationState {
+
+    /**
+     * We have requested a list of capabilities and are awaiting a reply.
+     */
     AWAITING_LIST,
+
+    /**
+     * We have sent a list of capabilities to enable, and are awaiting an acknowledgement.
+     */
     AWAITING_ACK,
+
+    /**
+     * Negotiation has completed.
+     */
     FINISHED
+
 }
 
+/**
+ * IRCv3 capabilities supported by the client.
+ */
 @Suppress("unused")
 sealed class Capability(val name: String) {
     // Capabilities that enable more information in message tags:
+    /** Messages are tagged with the server time they originated at. */
     object ServerTimeMessageTag : Capability("server-time")
+    /** Messages are tagged with the sender's account name. */
     object UserAccountMessageTag : Capability("account-tag")
 
     // Capabilities that extend existing commands to supply extra information:
+    /** Hosts are included for users in NAMES messages. */
     object HostsInNamesReply : Capability("userhost-in-names")
+    /** Multiple mode prefixes are returned per-user in NAMES messages. */
     object MultipleUserModePrefixes : Capability("multi-prefix")
+    /** The user's account and real name are provided when they join a channel. */
     object AccountAndRealNameInJoinMessages : Capability("extended-join")
 
     // Capabilities that affect how messages are sent/received:
+    /** Messages sent by the client are echo'd back on successful delivery. */
     object EchoMessages : Capability("echo-message")
 
     // Capabilities that notify us of changes to other clients:
+    /** Receive a notification when a user's account changes. */
     object AccountChangeMessages : Capability("account-notify") // TODO: Add processor
+    /** Receive a notification when a user's away state changes. */
     object AwayStateMessages : Capability("away-notify") // TODO: Add processor
+    /** Receive a notification when a user's host changes, instead of a quit/join. */
     object HostChangeMessages : Capability("chghost") // TODO: Add processor
+
 }
 
 internal val capabilities: Map<String, Capability> by lazy {

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

@@ -22,10 +22,19 @@ class CaseInsensitiveSet(private val caseMappingProvider: () -> CaseMapping) : I
         items.removeIf { caseMappingProvider().areEquivalent(it, item) }
     }
 
+    /**
+     * Determines if this set contains the given item, case-insensitively.
+     */
     operator fun contains(item: String) = items.any { caseMappingProvider().areEquivalent(it, item) }
 
+    /**
+     * Returns a read-only iterator over items in this set.
+     */
     override operator fun iterator() = items.iterator().iterator()
 
+    /**
+     * Returns true if this set is empty.
+     */
     fun isEmpty() = items.isEmpty()
 
 }

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

@@ -2,11 +2,25 @@ package com.dmdirc.ktirc.model
 
 import com.dmdirc.ktirc.io.CaseMapping
 
+/**
+ * Describes the state of a channel that the client has joined.
+ */
 class ChannelState(val name: String, caseMappingProvider: () -> CaseMapping) {
 
+    /**
+     * Whether or not we are in the process of receiving a user list (which may span many messages).
+     */
     var receivingUserList = false
+        internal set
+
+    /**
+     * A map of all users in the channel to their current modes.
+     */
     val users = ChannelUserMap(caseMappingProvider)
 
 }
 
+/**
+ * Describes a user in a channel, and their modes.
+ */
 data class ChannelUser(var nickname: String, var modes: String = "")

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

@@ -5,14 +5,19 @@ import com.dmdirc.ktirc.util.currentTimeZoneProvider
 import java.time.Instant
 import java.time.LocalDateTime
 
+/**
+ * Represents an IRC protocol message.
+ */
 class IrcMessage(val tags: Map<MessageTag, String>, val prefix: ByteArray?, val command: String, val params: List<ByteArray>) {
 
+    /** The time at which the message was sent, or our best guess at it. */
     val time: LocalDateTime = if (MessageTag.ServerTime in tags) {
         LocalDateTime.ofInstant(Instant.parse(tags[MessageTag.ServerTime]), currentTimeZoneProvider())
     } else {
         currentTimeProvider()
     }
 
+    /** The user that generated the message, if any. */
     val sourceUser by lazy {
         prefix?.asUser()?.apply {
             tags[MessageTag.AccountName]?.let { account = it }
@@ -21,8 +26,13 @@ class IrcMessage(val tags: Map<MessageTag, String>, val prefix: ByteArray?, val
 
 }
 
+/**
+ * Supported tags that may be applied to messages
+ */
 sealed class MessageTag(val name: String) {
+    /** Specifies the account name of the user, if the `account-tag` capability is negotiated. */
     object AccountName : MessageTag("account")
+    /** Specifies the time the server received the message, if the `server-time` capability is negotiated. */
     object ServerTime : MessageTag("time")
 }
 

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

@@ -2,10 +2,14 @@ package com.dmdirc.ktirc.model
 
 import com.dmdirc.ktirc.io.CaseMapping
 
+/**
+ * Provides a case-insensitive mapping from a String to some value, according to the provided [CaseMapping].
+ */
 abstract class CaseInsensitiveMap<T>(private val caseMappingProvider: () -> CaseMapping, private val nameOf: (T) -> String) : Iterable<T> {
 
     private val values = HashSet<T>()
 
+    /** Gets the value of the given key, if present. */
     operator fun get(name: String) = values.find { caseMappingProvider().areEquivalent(nameOf(it), name) }
 
     internal operator fun plusAssign(value: T) {
@@ -17,8 +21,10 @@ abstract class CaseInsensitiveMap<T>(private val caseMappingProvider: () -> Case
         values.removeIf { caseMappingProvider().areEquivalent(nameOf(it), name) }
     }
 
+    /** Returns true if the given key exists in this map. */
     operator fun contains(name: String) = get(name) != null
 
+    /** Provides a read-only iterator over the values in this map. */
     override fun iterator() = values.iterator().iterator()
 
     internal fun clear() = values.clear()
@@ -27,6 +33,11 @@ abstract class CaseInsensitiveMap<T>(private val caseMappingProvider: () -> Case
 
 }
 
+/** Maps a channel name to a [ChannelState] instance. */
 class ChannelStateMap(caseMappingProvider: () -> CaseMapping) : CaseInsensitiveMap<ChannelState>(caseMappingProvider, ChannelState::name)
+
+/** Maps a nickname to a [ChannelUser] instance. */
 class ChannelUserMap(caseMappingProvider: () -> CaseMapping) : CaseInsensitiveMap<ChannelUser>(caseMappingProvider, ChannelUser::nickname)
+
+/** Maps a nickname to a [KnownUser] instance. */
 class UserMap(caseMappingProvider: () -> CaseMapping) : CaseInsensitiveMap<KnownUser>(caseMappingProvider, { it.details.nickname })

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

@@ -1,3 +1,4 @@
 package com.dmdirc.ktirc.model
 
+/** Describes the client's profile information that will be provided to a server. */
 data class Profile(val initialNick: String, val realName: String, val userName: String)

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

@@ -1,3 +1,6 @@
 package com.dmdirc.ktirc.model
 
+/**
+ * Describes a server to connect to.
+ */
 data class Server(val host: String, val port: Int, val tls: Boolean = false, val password: String? = null)

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

@@ -27,10 +27,16 @@ class ServerState internal constructor(initialNickname: String) {
 
 }
 
+/**
+ * Maps known features onto their values, enforcing type safety.
+ */
 class ServerFeatureMap {
 
     private val features = HashMap<ServerFeature<*>, Any?>()
 
+    /**
+     * Gets the value, or the default value, of the given feature.
+     */
     @Suppress("UNCHECKED_CAST")
     operator fun <T : Any> get(feature: ServerFeature<T>) = features.getOrDefault(feature, feature.default) as? T? ?: feature.default
 
@@ -44,20 +50,35 @@ class ServerFeatureMap {
 
 }
 
+/**
+ * Stores the mapping of mode prefixes received from the server.
+ */
 data class ModePrefixMapping(val modes: String, val prefixes: String) {
 
+    /** Determines whether the given character is a mode prefix (e.g. "@", "+"). */
     fun isPrefix(char: Char) = prefixes.contains(char)
+    /** Gets the mode corresponding to the given prefix (e.g. "@" -> "o"). */
     fun getMode(prefix: Char) = modes[prefixes.indexOf(prefix)]
+    /** Gets the modes corresponding to the given prefixes (e.g. "@+" -> "ov"). */
     fun getModes(prefixes: String) = String(prefixes.map(this::getMode).toCharArray())
 
 }
 
+/**
+ * Describes a server feature determined from the 005 response.
+ */
 sealed class ServerFeature<T : Any>(val name: String, val type: KClass<T>, val default: T? = null) {
+    /** The case mapping the server uses, defaulting to RFC. */
     object ServerCaseMapping : ServerFeature<CaseMapping>("CASEMAPPING", CaseMapping::class, CaseMapping.Rfc)
+    /** The mode prefixes the server uses, defaulting to ov/@+. */
     object ModePrefixes : ServerFeature<ModePrefixMapping>("PREFIX", ModePrefixMapping::class, ModePrefixMapping("ov", "@+"))
+    /** The maximum number of channels a client may join. */
     object MaximumChannels : ServerFeature<Int>("MAXCHANNELS", Int::class) // TODO: CHANLIMIT also exists
+    /** The modes supported in channels. */
     object ChannelModes : ServerFeature<String>("CHANMODES", String::class)
+    /** The maximum length of a channel name, defaulting to 200. */
     object MaximumChannelNameLength : ServerFeature<Int>("CHANNELLEN", Int::class, 200)
+    /** Whether or not the server supports extended who. */
     object WhoxSupport : ServerFeature<Boolean>("WHOX", Boolean::class, false)
 }
 

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

@@ -1,5 +1,8 @@
 package com.dmdirc.ktirc.model
 
+/**
+ * Describes a user on IRC.
+ */
 data class User(
         var nickname: String,
         var ident: String? = null,
@@ -8,7 +11,7 @@ data class User(
         var realName: String? = null,
         var awayMessage: String? = null
 ) {
-    fun updateFrom(other: User) {
+    internal fun updateFrom(other: User) {
         nickname = other.nickname
         other.ident?.let { ident = it }
         other.hostname?.let { hostname = it }

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

@@ -2,6 +2,9 @@ package com.dmdirc.ktirc.model
 
 import com.dmdirc.ktirc.io.CaseMapping
 
+/**
+ * Keeps track of all known users that are in a common channel.
+ */
 class UserState(private val caseMappingProvider: () -> CaseMapping): Iterable<KnownUser> {
 
     private val users = UserMap(caseMappingProvider)
@@ -12,6 +15,7 @@ class UserState(private val caseMappingProvider: () -> CaseMapping): Iterable<Kn
     internal operator fun plusAssign(details: User) { users += KnownUser(caseMappingProvider, details) }
     internal operator fun minusAssign(details: User) { users -= details.nickname }
 
+    /** Provides a read-only iterator of all users. */
     override operator fun iterator() = users.iterator().iterator()
 
     internal fun removeIf(predicate: (KnownUser) -> Boolean) = users.removeIf(predicate)
@@ -30,12 +34,18 @@ class UserState(private val caseMappingProvider: () -> CaseMapping): Iterable<Kn
 
 }
 
+/**
+ * Describes a user we know about and the channels that caused them to be known.
+ */
 class KnownUser(caseMappingProvider: () -> CaseMapping, val details: User) {
 
+    /** The channels we have in common with the user. */
     val channels = CaseInsensitiveSet(caseMappingProvider)
 
     internal operator fun plusAssign(channel: String) { channels += channel }
     internal operator fun minusAssign(channel: String) { channels -= channel }
+
+    /** Determines if the user is in the specified channel. */
     operator fun contains(channel: String) = channel in channels
 
 }