From a8f3852478307b892f2dd1663c3095cc10c187be Mon Sep 17 00:00:00 2001
From: Janne Mareike Koschinski <janne@kuschku.de>
Date: Wed, 17 Feb 2021 00:51:46 +0100
Subject: [PATCH] Improve documentation
---
.../libquassel/client/io/StreamChannel.kt | 26 +++++++++++++++++++
.../libquassel/protocol/models/BackendInfo.kt | 19 ++++++++++++++
.../protocol/models/BackendInfoSerializer.kt | 9 +++++++
.../libquassel/protocol/models/SetupEntry.kt | 12 +++++++++
.../libquassel/protocol/util/pairs.kt | 7 +++++
.../libquassel/protocol/util/triples.kt | 6 +++++
6 files changed, 79 insertions(+)
diff --git a/libquassel-client/src/main/kotlin/de/justjanne/libquassel/client/io/StreamChannel.kt b/libquassel-client/src/main/kotlin/de/justjanne/libquassel/client/io/StreamChannel.kt
index b28f220..ecf433c 100644
--- a/libquassel-client/src/main/kotlin/de/justjanne/libquassel/client/io/StreamChannel.kt
+++ b/libquassel-client/src/main/kotlin/de/justjanne/libquassel/client/io/StreamChannel.kt
@@ -22,6 +22,9 @@ import java.util.zip.InflaterInputStream
import javax.net.ssl.SSLContext
import javax.net.ssl.SSLSocket
+/**
+ * Channel wrapping a Socket with support for TLS and compression layers
+ */
class StreamChannel constructor(
private val socket: Socket,
private val inputStream: InputStream = socket.getInputStream(),
@@ -30,11 +33,17 @@ class StreamChannel constructor(
private val input = ReadableWrappedChannel(inputStream)
private val output = WritableWrappedChannel(outputStream)
+ /**
+ * Return metadata about the current TLS session, if enabled
+ */
fun tlsInfo(): TlsInfo? {
val sslSocket = socket as? SSLSocket ?: return null
return TlsInfo.ofSession(sslSocket.session)
}
+ /**
+ * Return a copy of the current channel with DEFLATE compression
+ */
fun withCompression(): StreamChannel {
return StreamChannel(
socket,
@@ -43,6 +52,9 @@ class StreamChannel constructor(
)
}
+ /**
+ * Return a copy of the current channel with TLS
+ */
fun withTLS(
context: SSLContext,
): StreamChannel {
@@ -57,20 +69,34 @@ class StreamChannel constructor(
return StreamChannel(sslSocket)
}
+ /**
+ * Close the underlying streams and channels
+ */
override fun close() {
input.close()
output.close()
socket.close()
}
+ /**
+ * Returns whether the current channel is open, can be read from and written to
+ */
override fun isOpen(): Boolean {
return !socket.isClosed
}
+ /**
+ * Reads from the channel into a given byte buffer and returns the amount of
+ * written bytes
+ */
override fun read(dst: ByteBuffer): Int {
return input.read(dst)
}
+ /**
+ * Write a given byte buffer to the channel and return the amount of written
+ * bytes
+ */
override fun write(src: ByteBuffer): Int {
return output.write(src)
}
diff --git a/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/BackendInfo.kt b/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/BackendInfo.kt
index 80654ef..7107355 100644
--- a/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/BackendInfo.kt
+++ b/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/BackendInfo.kt
@@ -10,10 +10,29 @@
package de.justjanne.libquassel.protocol.models
+/**
+ * Model for storage/authenticator backend configuration
+ */
data class BackendInfo(
+ /**
+ * Configuration entries
+ */
val entries: List<SetupEntry>,
+ /**
+ * Whether or not this backend is default. Newer quassel clients use the first
+ * entry in the list instead of checking this field
+ */
val isDefault: Boolean,
+ /**
+ * User-visible name of the backend
+ */
val displayName: String,
+ /**
+ * User-visible description of the backend
+ */
val description: String,
+ /**
+ * ID
+ */
val backendId: String,
)
diff --git a/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/BackendInfoSerializer.kt b/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/BackendInfoSerializer.kt
index 09c150d..7198339 100644
--- a/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/BackendInfoSerializer.kt
+++ b/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/BackendInfoSerializer.kt
@@ -18,7 +18,13 @@ import de.justjanne.libquassel.protocol.variant.QVariant_
import de.justjanne.libquassel.protocol.variant.into
import de.justjanne.libquassel.protocol.variant.qVariant
+/**
+ * Handshake Serializer for [BackendInfo]
+ */
object BackendInfoSerializer {
+ /**
+ * Serialize backend info into a [QVariantMap] (for further serialization)
+ */
fun serialize(data: BackendInfo): QVariantMap = mapOf(
"SetupKeys" to qVariant<QStringList>(
data.entries.map(SetupEntry::key),
@@ -63,6 +69,9 @@ object BackendInfoSerializer {
SetupEntry(key.into(""), displayName.into(""), defaultValue)
} ?: defaults.map { (key, value) -> SetupEntry(key, key, value) }
+ /**
+ * Deserialize backend info from a [QVariantMap]
+ */
fun deserialize(data: QVariantMap) = BackendInfo(
entries = parseSetupEntries(
data["SetupData"].into<QVariantList>(),
diff --git a/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/SetupEntry.kt b/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/SetupEntry.kt
index 6675aac..e5ce295 100644
--- a/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/SetupEntry.kt
+++ b/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/models/SetupEntry.kt
@@ -12,8 +12,20 @@ package de.justjanne.libquassel.protocol.models
import de.justjanne.libquassel.protocol.variant.QVariant_
+/**
+ * Model of a backend configuration entry
+ */
data class SetupEntry(
+ /**
+ * Key for the configuration field
+ */
val key: String,
+ /**
+ * User-visible display name
+ */
val displayName: String,
+ /**
+ * Default value. The type of this value also determines the UI widget used.
+ */
val defaultValue: QVariant_,
)
diff --git a/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/util/pairs.kt b/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/util/pairs.kt
index 6ede523..794cb1a 100644
--- a/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/util/pairs.kt
+++ b/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/util/pairs.kt
@@ -10,10 +10,17 @@
package de.justjanne.libquassel.protocol.util
+/**
+ * Returns a partitioned list of pairs
+ */
fun <T> Iterable<T>.pairs(): List<Pair<T, T>> {
+ zipWithNext()
return pairs { a, b -> Pair(a, b) }
}
+/**
+ * Returns a partitioned list of pairs transformed with the given transformer
+ */
inline fun <T, R> Iterable<T>.pairs(transform: (a: T, b: T) -> R): List<R> {
val iterator = iterator()
val result = mutableListOf<R>()
diff --git a/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/util/triples.kt b/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/util/triples.kt
index 850300a..36bff4e 100644
--- a/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/util/triples.kt
+++ b/libquassel-protocol/src/main/kotlin/de/justjanne/libquassel/protocol/util/triples.kt
@@ -10,10 +10,16 @@
package de.justjanne.libquassel.protocol.util
+/**
+ * Returns a partitioned list of triples
+ */
fun <T> Iterable<T>.triples(): List<Triple<T, T, T>> {
return triples { a, b, c -> Triple(a, b, c) }
}
+/**
+ * Returns a partitioned list of triples transformed with the given transformer
+ */
inline fun <T, R> Iterable<T>.triples(transform: (a: T, b: T, c: T) -> R): List<R> {
val iterator = iterator()
val result = mutableListOf<R>()
--
GitLab