feature(scouting): Adding kdocs

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

@@ -21,28 +21,45 @@ import io.zenoh.jni.JNIScout
 import io.zenoh.scouting.Hello
 import io.zenoh.scouting.Scout
 import io.zenoh.scouting.WhatAmI
+import io.zenoh.scouting.WhatAmI.*
 import kotlinx.coroutines.channels.Channel
 
-/**
- * Static singleton class to load the Zenoh native library once and only once, as well as the logger in function of the
- * log level configuration.
- */
-internal expect object ZenohLoad
-
 object Zenoh {
 
+    /**
+     * Scout for routers and/or peers.
+     *
+     * Scout spawns a task that periodically sends scout messages and waits for Hello replies.
+     * Drop the returned Scout to stop the scouting task or explicitly call [Scout.stop] or [Scout.close].
+     *
+     * @param callback [Callback] to be run when receiving a [Hello] message.
+     * @param whatAmI [WhatAmI] configuration: it indicates the role of the zenoh node sending the HELLO message.
+     * @param config Optional [Config] for the scout.
+     * @return A [Scout] object.
+     */
     fun scout(
         callback: Callback<Hello>,
-        whatAmI: Set<WhatAmI> = setOf(WhatAmI.Peer),
+        whatAmI: Set<WhatAmI> = setOf(Peer, Router),
         config: Config? = null
     ): Scout<Unit> {
         ZenohLoad
         return JNIScout.scout(whatAmI = whatAmI, callback = callback, receiver = Unit, config = config)
     }
 
+    /**
+     * Scout for routers and/or peers.
+     *
+     * Scout spawns a task that periodically sends scout messages and waits for Hello replies.
+     * Drop the returned Scout to stop the scouting task or explicitly call [Scout.stop] or [Scout.close].
+     *
+     * @param handler [Handler] to handle incoming [Hello] messages.
+     * @param whatAmI [WhatAmI] configuration: it indicates the role of the zenoh node sending the HELLO message.
+     * @param config Optional [Config] for the scout.
+     * @return A [Scout] object.
+     */
     fun <R> scout(
         handler: Handler<Hello, R>,
-        whatAmI: Set<WhatAmI> = setOf(WhatAmI.Peer),
+        whatAmI: Set<WhatAmI> = setOf(Peer, Router),
         config: Config? = null
     ): Scout<R> {
         ZenohLoad
@@ -54,9 +71,20 @@ object Zenoh {
         )
     }
 
+    /**
+     * Scout for routers and/or peers.
+     *
+     * Scout spawns a task that periodically sends scout messages and waits for Hello replies.
+     * Drop the returned Scout to stop the scouting task or explicitly call [Scout.stop] or [Scout.close].
+     *
+     * @param channel [Channel] upon which the incoming [Hello] messages will be piped.
+     * @param whatAmI [WhatAmI] configuration: it indicates the role of the zenoh node sending the HELLO message.
+     * @param config Optional [Config] for the scout.
+     * @return A [Scout] object.
+     */
     fun scout(
         channel: Channel<Hello>,
-        whatAmI: Set<WhatAmI> = setOf(WhatAmI.Peer),
+        whatAmI: Set<WhatAmI> = setOf(Peer, Router),
         config: Config? = null
     ): Scout<Channel<Hello>> {
         ZenohLoad
@@ -68,4 +96,10 @@ object Zenoh {
             config = config
         )
     }
-}
+}
+
+/**
+ * Static singleton class to load the Zenoh native library once and only once, as well as the logger in function of the
+ * log level configuration.
+ */
+internal expect object ZenohLoad

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/Hello.kt

@@ -1,6 +1,28 @@
+//
+// Copyright (c) 2023 ZettaScale Technology
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+//
+// Contributors:
+//   ZettaScale Zenoh Team, <[email protected]>
+//
+
 package io.zenoh.scouting
 
 import io.zenoh.ZenohType
 import io.zenoh.protocol.ZenohID
 
-data class Hello(val whatAmI: WhatAmI, val zid: ZenohID, val locators: List<String>): ZenohType
+/**
+ * Hello message received while scouting.
+ *
+ * @property whatAmI [WhatAmI] configuration: it indicates the role of the zenoh node sending the HELLO message.
+ * @property zid [ZenohID] of the node sending the hello message.
+ * @property locators The locators of this hello message.
+ * @see Scout
+ */
+data class Hello(val whatAmI: WhatAmI, val zid: ZenohID, val locators: List<String>): ZenohType

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/Scout.kt

@@ -1,19 +1,51 @@
+//
+// Copyright (c) 2023 ZettaScale Technology
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+//
+// Contributors:
+//   ZettaScale Zenoh Team, <[email protected]>
+//
+
 package io.zenoh.scouting
 
 import io.zenoh.jni.JNIScout
 
+/**
+ * Scout for routers and/or peers.
+ *
+ * Scout spawns a task that periodically sends scout messages and waits for Hello replies.
+ * Drop the returned Scout to stop the scouting task.
+ *
+ * @param R The receiver type.
+ * @param receiver Receiver to handle incoming hello messages.
+ */
 class Scout<R> internal constructor(
     val receiver: R,
-    private val jniScout: JNIScout?
+    private var jniScout: JNIScout?
 ) : AutoCloseable {
 
+    /**
+     * Stops the scouting.
+     */
     fun stop() {
         jniScout?.close()
+        jniScout = null
     }
 
+    /**
+     * Equivalent to [stop].
+     */
     override fun close() {
         stop()
     }
-}
-
 
+    protected fun finalize() {
+        stop()
+    }
+}

zenoh-kotlin/src/commonMain/kotlin/io/zenoh/scouting/WhatAmI.kt

@@ -1,5 +1,24 @@
+//
+// Copyright (c) 2023 ZettaScale Technology
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+//
+// Contributors:
+//   ZettaScale Zenoh Team, <[email protected]>
+//
+
 package io.zenoh.scouting
 
+/**
+ * WhatAmI
+ *
+ * The role of the node sending the `hello` message.
+ */
 enum class WhatAmI(internal val value: Int) {
     Router(1),
     Peer(2),
@@ -8,4 +27,4 @@ enum class WhatAmI(internal val value: Int) {
     companion object {
         internal fun fromInt(value: Int) = entries.first { value == it.value }
     }
-}
+}