docs: completed Query methods documentation

Author: DadiBit

lib/src/main/kotlin/com/openmeteo/api/common/query/Query.kt

@@ -10,21 +10,38 @@ import kotlin.reflect.full.hasAnnotation
 import kotlin.reflect.full.memberProperties
 import kotlin.reflect.full.superclasses
 
+/**
+ * An HTTP query
+ */
 interface Query {
 
     companion object {
 
+        /**
+         * Try to find the SerialName of a key, looping over superclasses
+         */
         internal fun key(property: KProperty1<Query, *>, kClass: KClass<*>) =
+            // if the property has a custom SerialName get it
             property.findAnnotation<SerialName>()?.value
+                // else, loop over all superclasses, until a name is found
                 ?: kClass.superclasses.firstNotNullOfOrNull { superClass ->
                     superClass.memberProperties
+                        // if a superclass has the property we're looking for
                         .firstOrNull { it.name == property.name }
+                        // if the property has a custom SerialName get it
                         ?.findAnnotation<SerialName>()?.value
-                } ?: property.name
+                } ?: property.name // default to its name
 
+        /**
+         * Get the key name from a reified type
+         */
         internal inline fun <reified T> key(property: KProperty1<Query, *>) =
             key(property, T::class)
 
+        /**
+         * Stringify a value (arrays are ',' joined, enums are looked up for
+         * [SerialName]s; nulls are only filtered out from arrays)
+         */
         @OptIn(InternalSerializationApi::class, ExperimentalSerializationApi::class)
         internal fun value(any: Any?): String? =
             when (any) {
@@ -42,12 +59,21 @@ interface Query {
 
     }
 
+    /**
+     * Useful to convert, for example, spaces to "%20"
+     */
     private fun urlEncode(text: String) =
         URLEncoder.encode(text, "utf-8")
 
+    /**
+     * Calls the value companion method with `this` values
+     */
     private fun value(property: KProperty1<Query, *>) =
         Companion.value(property.get(this))
 
+    /**
+     * Get all non-Transient properties
+     */
     private val memberProperties
         get() =
             javaClass.kotlin.memberProperties
@@ -62,12 +88,21 @@ interface Query {
         memberProperties
             .mapNotNull { value(it)?.let { v -> key(it, javaClass.kotlin) to v } }
 
+    /**
+     * Like `.toList().toMap()`
+     */
     fun toMap() =
         toList().toMap()
 
+    /**
+     * URL encode the query as `?key0=value0&key1=value1&...keyN=valueN` format
+     */
     fun asString() =
         urlEncode(toList().joinToString("&", "?") { (k, v) -> "$k=$v" })
 
+    /**
+     * Replace the context [URL] query with this one
+     */
     fun toURL(context: URL) =
         URL(context, "${context.path}${asString()}")