Documentation fixes + improvements (#280)

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/Session.kt

@@ -214,11 +214,10 @@ class Session private constructor(private val config: Config) : AutoCloseable {
     }
 
     /**
-     * Declare a [Subscriber] on the session, specifying a channel pipe the received samples.
+     * Declare a [Subscriber] on the session, specifying a [Channel] to pipe the received samples.
      *
      * Example:
      * ```kotlin
-     *
      * Zenoh.open(Config.default()).onSuccess { session ->
      *     session.use {
      *         "demo/kotlin/sub".intoKeyExpr().onSuccess { keyExpr ->
@@ -263,7 +262,7 @@ class Session private constructor(private val config: Config) : AutoCloseable {
      *     "demo/kotlin/greeting".intoKeyExpr().onSuccess { keyExpr ->
      *         println("Declaring Queryable")
      *         val queryable = session.declareQueryable(keyExpr, callback = { query ->
-     *              query.replySuccess(keyExpr, payload = "Hello!".into())
+     *              query.reply(keyExpr, payload = ZBytes.from("Hello!"))
      *                   .onSuccess { println("Replied hello.") }
      *                   .onFailure { println(it) }
      *         }).getOrThrow()
@@ -273,7 +272,7 @@ class Session private constructor(private val config: Config) : AutoCloseable {
      *
      * @param keyExpr The [KeyExpr] the queryable will be associated to.
      * @param callback The callback to handle the received queries.
-     * @param onClose Callback to be run upon closing the queryable.
+     * @param onClose Optional callback to be run upon closing the queryable.
      * @param complete The queryable completeness.
      * @return A result with the queryable.
      * @see Query
@@ -295,7 +294,7 @@ class Session private constructor(private val config: Config) : AutoCloseable {
      *
      * ```kotlin
      * class ExampleHandler: Handler<Query, Unit> {
-     *     override fun handle(t: Query) = query.replySuccess(query.keyExpr, "Hello!".into())
+     *     override fun handle(t: Query) = query.reply(query.keyExpr, ZBytes.from("Hello!"))
      *
      *     override fun receiver() = Unit
      *
@@ -318,7 +317,7 @@ class Session private constructor(private val config: Config) : AutoCloseable {
      * @param keyExpr The [KeyExpr] the queryable will be associated to.
      * @param handler The [Handler] to handle the incoming queries. [Handler.onClose] will be called upon
      *  closing the queryable.
-     * @param onClose Callback to be run upon closing the queryable.
+     * @param onClose Optional callback to be run upon closing the queryable.
      * @param complete The completeness of the queryable.
      * @return A result with the queryable.
      */
@@ -348,7 +347,7 @@ class Session private constructor(private val config: Config) : AutoCloseable {
      *                     for (query in queryable.receiver) {
      *                         val valueInfo = query.value?.let { value -> " with value '$value'" } ?: ""
      *                         println(">> [Queryable] Received Query '${query.selector}' $valueInfo")
-     *                         query.replySuccess(keyExpr, payload = "Example reply".into())
+     *                         query.reply(keyExpr, payload = ZBytes.from("Example reply"))
      *                             .onSuccess { println(">> [Queryable ] Performed reply...") }
      *                             .onFailure { println(">> [Queryable ] Error sending reply: $it") }
      *                     }
@@ -446,38 +445,12 @@ class Session private constructor(private val config: Config) : AutoCloseable {
      * }
      * ```
      *
-     * Additionally, other optional parameters to the query can be specified, and the result
-     * of the operation can be checked as well:
-     *
-     * Example:
-     * ```kotlin
-     * Zenoh.open(Config.default()).onSuccess { session ->
-     *     session.use {
-     *         "a/b/c".intoSelector().onSuccess { selector ->
-     *             session.get(
-     *                 selector,
-     *                 callback = { reply -> println(reply) },
-     *                 payload = "Example payload".into(),
-     *                 encoding = Encoding(TEXT_PLAIN),
-     *                 target = QueryTarget.BEST_MATCHING,
-     *                 attachment = ZBytes.from("Example attachment"),
-     *                 timeout = Duration.ofMillis(1000),
-     *                 onClose = { println("Query terminated.") }
-     *             ).onSuccess {
-     *                 println("Get query launched...")
-     *             }.onFailure {
-     *                 println("Error: $it")
-     *             }
-     *         }
-     *     }
-     * }
-     * ```
-     *
      * @param selector The [Selector] on top of which the get query will be performed.
      * @param callback [Callback] to handle the replies.
-     * @param payload Optional [ZBytes] payload for the query.
+     * @param payload Optional payload for the query.
      * @param encoding Encoding of the [payload].
      * @param attachment Optional attachment.
+     * @param timeout Timeout of the query.
      * @param target The [QueryTarget] of the query.
      * @param consolidation The [ConsolidationMode] configuration.
      * @param onClose Callback to be executed when the query is terminated.
@@ -549,43 +522,12 @@ class Session private constructor(private val config: Config) : AutoCloseable {
      * }
      * ```
      *
-     * Additionally, other optional parameters to the query can be specified, and the result
-     * of the operation can be checked as well:
-     *
-     * Example:
-     * ```kotlin
-     * Zenoh.open(Config.default()).onSuccess { session ->
-     *     session.use {
-     *         "a/b/c".intoSelector().onSuccess { selector ->
-     *             val handler = QueueHandler<Reply>()
-     *             session.get(
-     *                 selector,
-     *                 handler,
-     *                 payload = "Example payload".into(),
-     *                 encoding = Encoding.TEXT_PLAIN,
-     *                 target = QueryTarget.BEST_MATCHING,
-     *                 attachment = ZBytes.from("Example attachment"),
-     *                 timeout = Duration.ofMillis(1000),
-     *                 onClose = { println("Query terminated.") }
-     *             ).onSuccess { receiver ->
-     *                 println("Get query launched...")
-     *                 // ...
-     *                 for (reply in receiver) {
-     *                     println(reply)
-     *                 }
-     *             }.onFailure {
-     *                 println("Error: $it")
-     *             }
-     *         }
-     *     }
-     * }
-     * ```
-     *
      * @param selector The [Selector] on top of which the get query will be performed.
      * @param handler [Handler] to handle the replies.
-     * @param payload Optional [ZBytes] payload for the query.
+     * @param payload Optional payload for the query.
      * @param encoding Encoding of the [payload].
      * @param attachment Optional attachment.
+     * @param timeout Timeout of the query.
      * @param target The [QueryTarget] of the query.
      * @param consolidation The [ConsolidationMode] configuration.
      * @param onClose Callback to be executed when the query is terminated.
@@ -643,42 +585,12 @@ class Session private constructor(private val config: Config) : AutoCloseable {
      * }
      * ```
      *
-     * Additionally, other optional parameters to the query can be specified, and the result
-     * of the operation can be checked as well:
-     *
-     * Example:
-     *
-     * ```kotlin
-     * Zenoh.open(Config.default()).onSuccess { session ->
-     *     session.use {
-     *         "a/b/c".intoSelector().onSuccess { selector ->
-     *               session.get(selector,
-     *                   channel = Channel(),
-     *                   payload = "Example payload".into(),
-     *                   encoding = Encoding.TEXT_PLAIN,
-     *                   target = QueryTarget.BEST_MATCHING,
-     *                   attachment = ZBytes.from("Example attachment"),
-     *                   timeout = Duration.ofMillis(1000),
-     *                   onClose = { println("Query terminated.") }
-     *               ).onSuccess { channel ->
-     *                   runBlocking {
-     *                       for (reply in channel) {
-     *                           println("Received $reply")
-     *                       }
-     *                   }
-     *               }.onFailure {
-     *                    println("Error: $it")
-     *               }
-     *          }
-     *     }
-     * }
-     * ```
-     *
      * @param selector The [Selector] on top of which the get query will be performed.
      * @param channel Blocking [Channel] to handle the replies.
-     * @param payload Optional [ZBytes] payload for the query.
+     * @param payload Optional payload for the query.
      * @param encoding Encoding of the [payload].
      * @param attachment Optional attachment.
+     * @param timeout Timeout of the query.
      * @param target The [QueryTarget] of the query.
      * @param consolidation The [ConsolidationMode] configuration.
      * @param onClose Callback to be executed when the query is terminated.
@@ -723,37 +635,16 @@ class Session private constructor(private val config: Config) : AutoCloseable {
      * Zenoh.open(config).onSuccess { session ->
      *     session.use {
      *         "a/b/c".intoKeyExpr().onSuccess { keyExpr ->
-     *             session.put(keyExpr, payload = "Example payload".into()).getOrThrow()
-     *         }
-     *         // ...
-     *     }
-     * }
-     * ```
-     *
-     * Additionally, a [QoS] configuration can be specified as well as an attachment, for instance:
-     * ```kotlin
-     * Zenoh.open(Config.default()).onSuccess { session ->
-     *     session.use {
-     *         "a/b/c".intoKeyExpr().onSuccess { keyExpr ->
-     *             val exampleQoS = QoS(
-     *                  congestionControl = CongestionControl.DROP,
-     *                  express = true,
-     *                  priority = Priority.DATA_HIGH)
-     *             val exampleAttachment = "exampleAttachment".into()
-     *             session.put(
-     *                  keyExpr,
-     *                  payload = "Example payload".into(),
-     *                  encoding = Encoding.TEXT_PLAIN,
-     *                  qos = exampleQoS,
-     *                  attachment = exampleAttachment).getOrThrow()
+     *             session.put(keyExpr, payload = ZBytes.from("Example payload")).getOrThrow()
      *         }
      *         // ...
      *     }
      * }
      * ```
      *
      * @param keyExpr The [KeyExpr] to be used for the put operation.
-     * @param payload The [ZBytes] to be put.
+     * @param payload The payload to be put.
+     * @param encoding The [Encoding] of the payload.
      * @param qos The [QoS] configuration.
      * @param attachment Optional attachment.
      * @param reliability The [Reliability] configuration.
@@ -762,12 +653,12 @@ class Session private constructor(private val config: Config) : AutoCloseable {
     fun put(
         keyExpr: KeyExpr,
         payload: IntoZBytes,
-        encoding: Encoding? = null,
+        encoding: Encoding = Encoding.default(),
         qos: QoS = QoS.default(),
         attachment: IntoZBytes? = null,
         reliability: Reliability = Reliability.RELIABLE
     ): Result<Unit> {
-        val put = Put(keyExpr, payload.into(), encoding ?: Encoding.default(), qos, attachment?.into(), reliability)
+        val put = Put(keyExpr, payload.into(), encoding, qos, attachment?.into(), reliability)
         return resolvePut(keyExpr, put)
     }
 
@@ -779,8 +670,9 @@ class Session private constructor(private val config: Config) : AutoCloseable {
      * Zenoh.open(config).onSuccess { session ->
      *     session.use {
      *         key.intoKeyExpr().onSuccess { keyExpr ->
-     *             println("Deleting resources matching '$keyExpr'...")
-     *             session.delete(keyExpr)
+     *             session.delete(keyExpr).onSuccess {
+     *                 println("Deleting resources matching '$keyExpr'...")
+     *             }
      *         }
      *     }
      * }

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/ZenohType.kt

@@ -2,8 +2,8 @@ package io.zenoh
 
 /**
  * Zenoh type. An empty interface to regroup elements of type [io.zenoh.sample.Sample],
- * [io.zenoh.query.Reply] and [io.zenoh.queryable.Query].
+ * [io.zenoh.query.Reply], and [io.zenoh.query.Query].
  *
- * This kind of elements have in common that they can be received through the Zenoh network.
+ * These kinds of elements have in common that they can be received through the Zenoh network.
  */
 interface ZenohType

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/bytes/IntoZBytes.kt

@@ -9,7 +9,7 @@ package io.zenoh.bytes
  * ```kotlin
  * class Foo(val content: String) : IntoZBytes {
  *
- *   override fun into(): ZBytes = content.into()
+ *   override fun into(): ZBytes = ZBytes.from(content)
  * }
  * ```
  */

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/handlers/Handler.kt

@@ -65,7 +65,7 @@ interface Handler<T: ZenohType, R> {
     /**
      * This callback is invoked by Zenoh at the conclusion of the handler's lifecycle.
      *
-     * For instances of [io.zenoh.queryable.Queryable] and [io.zenoh.subscriber.Subscriber],
+     * For instances of [io.zenoh.query.Queryable] and [io.zenoh.pubsub.Subscriber],
      * Zenoh triggers this callback when they are closed or undeclared. In the case of a Get query
      * it is invoked when no more elements of type [T] are expected to be received.
      */

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/jni/JNIPublisher.kt

@@ -17,9 +17,10 @@ package io.zenoh.jni
 import io.zenoh.exceptions.ZError
 import io.zenoh.bytes.Encoding
 import io.zenoh.bytes.IntoZBytes
+import io.zenoh.pubsub.Publisher
 
 /**
- * Adapter class to handle the interactions with Zenoh through JNI for a [io.zenoh.publication.Publisher].
+ * Adapter class to handle the interactions with Zenoh through JNI for a [Publisher].
  *
  * @property ptr: raw pointer to the underlying native Publisher.
  */

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/jni/JNIQueryable.kt

@@ -15,7 +15,7 @@
 package io.zenoh.jni
 
 /**
- * Adapter class to handle the interactions with Zenoh through JNI for a [io.zenoh.queryable.Queryable]
+ * Adapter class to handle the interactions with Zenoh through JNI for a [io.zenoh.query.Queryable]
  *
  * @property ptr: raw pointer to the underlying native Queryable.
  */

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/jni/JNISubscriber.kt

@@ -14,8 +14,10 @@
 
 package io.zenoh.jni
 
+import io.zenoh.pubsub.Subscriber
+
 /**
- * Adapter class to handle the interactions with Zenoh through JNI for a [io.zenoh.subscriber.Subscriber]
+ * Adapter class to handle the interactions with Zenoh through JNI for a [Subscriber]
  *
  * @property ptr: raw pointer to the underlying native Subscriber.
  */

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/keyexpr/KeyExpr.kt

@@ -49,15 +49,9 @@ import io.zenoh.jni.JNIKeyExpr
  * A [KeyExpr] acts as a container for the string representation of a key expression. Operations like `intersects`,
  * `includes`, and `equals` are processed at the native layer using this string representation. For improved performance,
  * consider initializing a [KeyExpr] through [Session.declareKeyExpr]. This method associates the [KeyExpr] with a native
- * instance, thereby optimizing operation execution. However, it is crucial to manually invoke [close] on each [KeyExpr]
- * instance before it is garbage collected to prevent memory leaks.
+ * instance, thereby optimizing operation execution.
  *
- * As an alternative, employing a try-with-resources pattern using Kotlin's `use` block is recommended. This approach
- * ensures that [close] is automatically called, safely managing the lifecycle of the [KeyExpr] instance.
- *
- * @param keyExpr The string representation of the key expression.
- * @param jniKeyExpr An optional [JNIKeyExpr] instance, present when the key expression was declared through [Session.declareKeyExpr],
- *  it represents the native instance of the key expression.
+ * For more information, checkout the [key expressions RFC](https://github.com/eclipse-zenoh/roadmap/blob/main/rfcs/ALL/Key%20Expressions.md).
  */
 class KeyExpr internal constructor(internal val keyExpr: String, internal var jniKeyExpr: JNIKeyExpr? = null): AutoCloseable,
     SessionDeclaration {
@@ -94,42 +88,42 @@ class KeyExpr internal constructor(internal val keyExpr: String, internal var jn
     }
 
     /**
-     * Intersects operation. This method returns `True` if there exists at least one key that belongs to both sets
-     * defined by `this` and `other`.
-     * Will return false as well if the key expression is not valid anymore.
+     * Intersects operation.
+     *
+     * This method returns `True` if there exists at least one key that belongs to both sets defined by `this` and the `other` key expressions.
      */
     fun intersects(other: KeyExpr): Boolean {
          return JNIKeyExpr.intersects(this, other)
     }
 
     /**
-     * Includes operation. This method returns `true` when all the keys defined by `other` also belong to the set
-     * defined by `this`.
-     * Will return false as well if the key expression is not valid anymore.
+     * Includes operation.
+     *
+     * This method returns `true` when all the keys defined by `other` also belong to the set defined by `this`.
      */
     fun includes(other: KeyExpr): Boolean {
         return JNIKeyExpr.includes(this, other)
     }
 
     /**
-     * Returns the relation between 'this' and other from 'this''s point of view (SetIntersectionLevel::Includes
-     * signifies that self includes other). Note that this is slower than [intersects] and [includes],
+     * Returns the relation between 'this' and `other` from 'this''s point of view (`SetIntersectionLevel::Includes`
+     * signifies that `this` includes other). Note that this is slower than [intersects] and [includes],
      * so you should favor these methods for most applications.
      */
     fun relationTo(other: KeyExpr): SetIntersectionLevel {
         return JNIKeyExpr.relationTo(this, other)
     }
 
     /**
-     * Joins both sides, inserting a / in between them.
+     * Joins both sides, inserting a `/` in between them.
      * This should be your preferred method when concatenating path segments.
      */
     fun join(other: String): Result<KeyExpr> {
         return JNIKeyExpr.joinViaJNI(this, other)
     }
 
     /**
-     * Performs string concatenation and returns the result as a KeyExpr if possible.
+     * Performs string concatenation and returns the result as a `KeyExpr` if possible.
      * You should probably prefer [join] as Zenoh may then take advantage of the hierarchical separation it inserts.
      */
     fun concat(other: String): Result<KeyExpr> {