Improves documentation

Author: Abhijit Sarkar

gradle.properties

@@ -10,7 +10,7 @@ ktlintVersion=9.4.0
 bintrayPluginVersion=1.8.5
 
 projectGroup=com.asarkar.spring
-projectVersion=1.0.6
+projectVersion=1.0.7
 projectDescription=Starts the Cassandra server and makes the ports available as Spring Boot environment properties
 licenseName=Apache-2.0
 licenseUrl=http://www.apache.org/licenses/LICENSE-2.0.txt

src/main/kotlin/com/asarkar/spring/test/CassandraUnit.kt

@@ -7,6 +7,12 @@ import java.lang.reflect.Field
 import java.nio.file.Files
 import java.nio.file.Paths
 
+/**
+ * Utility to start the server and clean up any files left behind.
+ *
+ * @author Abhijit Sarkar
+ * @since 1.0.5
+ */
 internal object CassandraUnit {
     private val cassandraDaemon: Field =
         ReflectionUtils.findField(EmbeddedCassandraServerHelper::class.java, "cassandraDaemon")!!
@@ -18,11 +24,13 @@ internal object CassandraUnit {
         else EmbeddedCassandraServerHelper.startEmbeddedCassandra(config, timeout)
     }
 
+    // https://github.com/jsevellec/cassandra-unit/issues/319
     fun cleanUp() {
         val log4jConfigFile =
             EmbeddedCassandraServerHelper.DEFAULT_TMP_DIR + EmbeddedCassandraServerHelper.DEFAULT_LOG4J_CONFIG_FILE
         Files.deleteIfExists(Paths.get(log4jConfigFile))
     }
 
+    // https://github.com/jsevellec/cassandra-unit/issues/318
     fun isRunning(): Boolean = cassandraDaemon.get(null) != null
 }

src/main/kotlin/com/asarkar/spring/test/CassandraUnitApplicationListener.kt

@@ -17,20 +17,32 @@ import java.nio.file.Files
 import java.nio.file.Paths
 import kotlin.concurrent.thread
 
+/**
+ * Listener that prepares the environment so that CassandraUnit will work when it is initialized.
+ * For instance, by finding free ports for the server to listen on.
+ *
+ * @author Abhijit Sarkar
+ * @since 1.0.0
+ */
 @Order(Ordered.LOWEST_PRECEDENCE)
 class CassandraUnitApplicationListener : ApplicationListener<ApplicationPreparedEvent> {
     private val log = LoggerFactory.getLogger(CassandraUnitApplicationListener::class.java)
     private val prefix = "cassandra-unit"
 
     override fun onApplicationEvent(event: ApplicationPreparedEvent) {
         val env = event.applicationContext.environment
+        // If the config is not found it means the AutoConfigureCassandraUnit hasn't been initialized.
         val config = env.getProperty("$prefix.config", String::class.java) ?: return
+        // Already running; get the ports from EmbeddedCassandraServerHelper.
         val cassandra = if (CassandraUnit.isRunning()) {
             mapOf(
                 "$prefix.native-transport-port" to EmbeddedCassandraServerHelper.getNativeTransportPort(),
                 "$prefix.rpc-port" to EmbeddedCassandraServerHelper.getRpcPort()
             )
         } else {
+            // If using default config with known ports, parse the config for the ports.
+            // If not using default config, assign a free port to whichever one is zero, and create a new
+            // config file.
             val outFile = config.takeIf { it != EmbeddedCassandraServerHelper.DEFAULT_CASSANDRA_YML_FILE }
                 ?.let { this.createTempFile(it) }
             discoverPorts(config, outFile).also {
@@ -64,13 +76,19 @@ class CassandraUnitApplicationListener : ApplicationListener<ApplicationPrepared
                 var portName: String? = null
                 Yaml().parse(reader)
                     .forEach {
+                        // If not a ScalarEvent, pass-through.
                         if (it !is ScalarEvent) emitter?.emit(it)
                         else {
+                            // Try to get the port name and value from the event.
                             val (name, value) = getPortNameAndValue(it, portName)
+                            // Existing port value is zero; new value assigned.
                             if (value != null) {
                                 cassandra["$prefix.$portName"] = value
                                 emitter?.emit(it.withValue(value))
-                            } else emitter?.emit(it)
+                            }
+                            // No need to modify the event; either it isn't a port, or the existing
+                            // port value isn't zero.
+                            else emitter?.emit(it)
                             portName = name
                         }
                     }
@@ -80,9 +98,12 @@ class CassandraUnitApplicationListener : ApplicationListener<ApplicationPrepared
     }
 
     private fun getPortNameAndValue(event: ScalarEvent, portName: String?): Pair<String?, Int?> {
+        // Found a port key.
         if (portName == null && event.value.endsWith("_port")) {
             return event.value.replace('_', '-') to null
-        } else if (portName != null) {
+        }
+        // Found the port value corresponding to the key found previously.
+        else if (portName != null) {
             val port = if (event.value.matches("0+".toRegex())) SocketUtils.findAvailableTcpPort()
             else event.value.toInt()
             return null to port