Add more docs

detekt.yml

@@ -1,3 +1,7 @@
+comments:
+  UndocumentedPublicClass:
+    active: true
+
 exceptions:
   TooGenericExceptionCaught:
     active: false

src/main/kotlin/de/smartsquare/starter/mqtt/MqttConnector.kt

@@ -17,6 +17,9 @@ import java.util.concurrent.CompletableFuture
 import java.util.concurrent.TimeUnit
 import java.util.concurrent.TimeoutException
 
+/**
+ * Base class for connectors implementing common logic.
+ */
 abstract class MqttConnector : SmartLifecycle {
 
     companion object {
@@ -34,6 +37,9 @@ abstract class MqttConnector : SmartLifecycle {
     abstract override fun stop(callback: Runnable)
 }
 
+/**
+ * Class responsible for connecting a client (mqtt 3) and subscribing to collected topics.
+ */
 class Mqtt3Connector(
     client: Mqtt3Client,
     private val collector: MqttSubscriberCollector,
@@ -100,6 +106,9 @@ class Mqtt3Connector(
     override fun isRunning() = client.state != MqttClientState.DISCONNECTED
 }
 
+/**
+ * Class responsible for connecting a client (mqtt 5) and subscribing to collected topics.
+ */
 class Mqtt5Connector(
     client: Mqtt5Client,
     private val collector: MqttSubscriberCollector,

src/main/kotlin/de/smartsquare/starter/mqtt/MqttExceptions.kt

@@ -1,5 +1,7 @@
 package de.smartsquare.starter.mqtt
 
+import com.hivemq.client.mqtt.datatypes.MqttTopic
+
 /**
  * Exception thrown when invalid methods with [MqttSubscribe] are found.
  */
@@ -9,3 +11,13 @@ class MqttConfigurationException(message: String) : RuntimeException(message)
  * Exception thrown when the connection to mqtt broker fails.
  */
 class MqttBrokerConnectException(message: String, cause: Throwable? = null) : RuntimeException(message, cause)
+
+/**
+ * Exception thrown when processing a single mqtt message fails.
+ */
+class MqttMessageException(
+    val topic: MqttTopic,
+    val payload: ByteArray,
+    message: String? = null,
+    cause: Throwable? = null,
+) : RuntimeException(message, cause)

src/main/kotlin/de/smartsquare/starter/mqtt/MqttExecutor.kt

@@ -3,6 +3,10 @@ package de.smartsquare.starter.mqtt
 import org.springframework.context.event.ContextClosedEvent
 import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor
 
+/**
+ * Custom executor suitable for processing mqtt messages. It is configured to support a graceful shutdown - Remaining
+ * messages are processed for a configurable amount of time until stopped.
+ */
 class MqttExecutor : ThreadPoolTaskExecutor() {
 
     init {

src/main/kotlin/de/smartsquare/starter/mqtt/MqttHandler.kt

@@ -8,6 +8,9 @@ import org.slf4j.LoggerFactory
 import java.lang.reflect.InvocationTargetException
 import java.util.concurrent.ConcurrentHashMap
 
+/**
+ * Class for consuming and forwarding messages to the correct subscriber.
+ */
 class MqttHandler(
     private val collector: MqttSubscriberCollector,
     private val adapter: MqttMessageAdapter,
@@ -18,6 +21,10 @@ class MqttHandler(
 
     private val subscriberCache = ConcurrentHashMap<MqttTopic, ResolvedMqttSubscriber>(collector.subscribers.size)
 
+    /**
+     * Handles a single message. The [topic] is used to determine the correct subscriber which is then invoked with
+     * parameters produced by the [MqttMessageAdapter].
+     */
     fun handle(topic: MqttTopic, payload: ByteArray) {
         if (logger.isTraceEnabled) {
             logger.trace("Received mqtt message on topic [$topic] with payload ${payload.toString(Charsets.UTF_8)}")

src/main/kotlin/de/smartsquare/starter/mqtt/MqttSubscriberCollector.kt

@@ -76,5 +76,8 @@ class MqttSubscriberCollector(private val config: MqttProperties) : BeanPostProc
         return topicParamCount > 1 || payloadParamCount > 1
     }
 
+    /**
+     * Data class representing a subscriber method annotated with [MqttSubscribe].
+     */
     data class ResolvedMqttSubscriber(val bean: Any, val method: Method, val topic: MqttTopicFilter, val qos: MqttQos)
 }