doc: improve connection docs

Closes #799

Signed-off-by: Yuki Kishimoto <[email protected]>

Author: yukibtc

bindings/nostr-sdk-ffi/src/client/mod.rs

@@ -177,6 +177,14 @@ impl Client {
     }
 
     /// Connect to all added relays
+    ///
+    /// Attempts to initiate a connection for every relay currently in
+    /// [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`].
+    /// A background connection task is spawned for each such relay, which then tries
+    /// to establish the connection.
+    /// Any relay not in one of these two statuses is skipped.
+    ///
+    /// For further details, see the documentation of [`Relay::connect`].
     pub async fn connect(&self) {
         self.inner.connect().await
     }
@@ -191,10 +199,14 @@ impl Client {
 
     /// Try to establish a connection with the relays.
     ///
-    /// Attempts to establish a connection without spawning the connection task if it fails.
+    /// Attempts to establish a connection for every relay currently in
+    /// [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`]
+    /// without spawning the connection task if it fails.
     /// This means that if the connection fails, no automatic retries are scheduled.
     /// Use [`Client::connect`] if you want to immediately spawn a connection task,
     /// regardless of whether the initial connection succeeds.
+    ///
+    /// For further details, see the documentation of [`Relay::try_connect`].
     pub async fn try_connect(&self, timeout: Duration) -> Output {
         self.inner.try_connect(timeout).await.into()
     }

bindings/nostr-sdk-ffi/src/relay/mod.rs

@@ -162,18 +162,42 @@ impl Relay {
 
     // TODO: add notifications
 
-    /// Connect to relay
+    /// Connect to the relay
+    ///
+    /// # Overview
+    ///
+    /// If the relay’s status is not [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`],
+    /// this method returns immediately without doing anything.
+    /// Otherwise, the connection task will be spawned, which will attempt to connect to relay.
     ///
     /// This method returns immediately and doesn't provide any information on if the connection was successful or not.
+    ///
+    /// # Automatic reconnection
+    ///
+    /// By default, in case of disconnection, the connection task will automatically attempt to reconnect.
+    /// This behavior can be disabled by changing [`RelayOptions::reconnect`] option.
     pub fn connect(&self) {
         self.inner.connect()
     }
 
-    /// Try to connect to relay
+    /// Try to establish a connection with the relay.
+    ///
+    /// # Overview
+    ///
+    /// If the relay’s status is not [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`],
+    /// this method returns immediately without doing anything.
+    /// Otherwise, attempts to establish a connection without spawning the connection task if it fails.
+    /// This means that if the connection fails, no automatic retries are scheduled.
+    /// Use [`Relay::connect`] if you want to immediately spawn a connection task,
+    /// regardless of whether the initial connection succeeds.
+    ///
+    /// Returns an error if the connection fails.
+    ///
+    /// # Automatic reconnection
     ///
-    /// This method returns an error if the connection fails.
-    /// If the connection fails,
-    /// a task will continue to retry in the background (unless configured differently in `RelayOptions`.
+    /// By default, in case of disconnection (after a first successful connection),
+    /// the connection task will automatically attempt to reconnect.
+    /// This behavior can be disabled by changing [`RelayOptions::reconnect`] option.
     pub async fn try_connect(&self, timeout: Duration) -> Result<()> {
         Ok(self.inner.try_connect(timeout).await?)
     }

bindings/nostr-sdk-js/src/client/mod.rs

@@ -205,6 +205,14 @@ impl JsClient {
     }
 
     /// Connect to all added relays
+    ///
+    /// Attempts to initiate a connection for every relay currently in
+    /// [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`].
+    /// A background connection task is spawned for each such relay, which then tries
+    /// to establish the connection.
+    /// Any relay not in one of these two statuses is skipped.
+    ///
+    /// For further details, see the documentation of [`Relay::connect`].
     pub async fn connect(&self) {
         self.inner.connect().await
     }
@@ -220,10 +228,14 @@ impl JsClient {
 
     /// Try to establish a connection with the relays.
     ///
-    /// Attempts to establish a connection without spawning the connection task if it fails.
+    /// Attempts to establish a connection for every relay currently in
+    /// [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`]
+    /// without spawning the connection task if it fails.
     /// This means that if the connection fails, no automatic retries are scheduled.
     /// Use [`Client::connect`] if you want to immediately spawn a connection task,
     /// regardless of whether the initial connection succeeds.
+    ///
+    /// For further details, see the documentation of [`Relay::try_connect`].
     #[wasm_bindgen(js_name = tryConnect)]
     pub async fn try_connect(&self, timeout: &JsDuration) -> JsOutput {
         self.inner.try_connect(**timeout).await.into()

bindings/nostr-sdk-js/src/relay/mod.rs

@@ -141,18 +141,42 @@ impl JsRelay {
         self.inner.queue() as u64
     }
 
-    /// Connect to relay
+    /// Connect to the relay
+    ///
+    /// # Overview
+    ///
+    /// If the relay’s status is not [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`],
+    /// this method returns immediately without doing anything.
+    /// Otherwise, the connection task will be spawned, which will attempt to connect to relay.
     ///
     /// This method returns immediately and doesn't provide any information on if the connection was successful or not.
+    ///
+    /// # Automatic reconnection
+    ///
+    /// By default, in case of disconnection, the connection task will automatically attempt to reconnect.
+    /// This behavior can be disabled by changing [`RelayOptions::reconnect`] option.
     pub fn connect(&self) {
         self.inner.connect()
     }
 
-    /// Try to connect to relay
+    /// Try to establish a connection with the relay.
+    ///
+    /// # Overview
+    ///
+    /// If the relay’s status is not [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`],
+    /// this method returns immediately without doing anything.
+    /// Otherwise, attempts to establish a connection without spawning the connection task if it fails.
+    /// This means that if the connection fails, no automatic retries are scheduled.
+    /// Use [`Relay::connect`] if you want to immediately spawn a connection task,
+    /// regardless of whether the initial connection succeeds.
+    ///
+    /// Returns an error if the connection fails.
+    ///
+    /// # Automatic reconnection
     ///
-    /// This method returns an error if the connection fails.
-    /// If the connection fails,
-    /// a task will continue to retry in the background (unless configured differently in `RelayOptions`.
+    /// By default, in case of disconnection (after a first successful connection),
+    /// the connection task will automatically attempt to reconnect.
+    /// This behavior can be disabled by changing [`RelayOptions::reconnect`] option.
     #[wasm_bindgen(js_name = tryConnect)]
     pub async fn try_connect(&self, timeout: &JsDuration) -> Result<()> {
         self.inner.try_connect(**timeout).await.map_err(into_err)

crates/nostr-relay-pool/src/pool/mod.rs

@@ -320,6 +320,17 @@ impl RelayPool {
     }
 
     /// Connect to all added relays
+    ///
+    /// Attempts to initiate a connection for every relay currently in
+    /// [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`].
+    /// A background connection task is spawned for each such relay, which then tries
+    /// to establish the connection.
+    /// Any relay not in one of these two statuses is skipped.
+    ///
+    /// For further details, see the documentation of [`Relay::connect`].
+    ///
+    /// [`RelayStatus::Initialized`]: crate::relay::RelayStatus::Initialized
+    /// [`RelayStatus::Terminated`]: crate::relay::RelayStatus::Terminated
     pub async fn connect(&self) {
         // Lock with read shared access
         let relays = self.inner.atomic.relays.read().await;
@@ -350,7 +361,9 @@ impl RelayPool {
 
     /// Try to establish a connection with the relays.
     ///
-    /// Attempts to establish a connection without spawning the connection task if it fails.
+    /// Attempts to establish a connection for every relay currently in
+    /// [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`]
+    /// without spawning the connection task if it fails.
     /// This means that if the connection fails, no automatic retries are scheduled.
     /// Use [`RelayPool::connect`] if you want to immediately spawn a connection task,
     /// regardless of whether the initial connection succeeds.

crates/nostr-relay-pool/src/relay/mod.rs

@@ -231,10 +231,22 @@ impl Relay {
         self.inner.internal_notification_sender.subscribe()
     }
 
-    /// Connect to relay
+    /// Connect to the relay
+    ///
+    /// # Overview
+    ///
+    /// If the relay’s status is not [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`],
+    /// this method returns immediately without doing anything.
+    /// Otherwise, the connection task will be spawned, which will attempt to connect to relay.
     ///
     /// This method returns immediately and doesn't provide any information on if the connection was successful or not.
+    ///
+    /// # Automatic reconnection
+    ///
+    /// By default, in case of disconnection, the connection task will automatically attempt to reconnect.
+    /// This behavior can be disabled by changing [`RelayOptions::reconnect`] option.
     pub fn connect(&self) {
+        // Immediately return if can't connect
         if !self.status().can_connect() {
             return;
         }
@@ -279,12 +291,22 @@ impl Relay {
 
     /// Try to establish a connection with the relay.
     ///
-    /// Attempts to establish a connection without spawning the connection task if it fails.
+    /// # Overview
+    ///
+    /// If the relay’s status is not [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`],
+    /// this method returns immediately without doing anything.
+    /// Otherwise, attempts to establish a connection without spawning the connection task if it fails.
     /// This means that if the connection fails, no automatic retries are scheduled.
     /// Use [`Relay::connect`] if you want to immediately spawn a connection task,
     /// regardless of whether the initial connection succeeds.
     ///
     /// Returns an error if the connection fails.
+    ///
+    /// # Automatic reconnection
+    ///
+    /// By default, in case of disconnection (after a first successful connection),
+    /// the connection task will automatically attempt to reconnect.
+    /// This behavior can be disabled by changing [`RelayOptions::reconnect`] option.
     pub async fn try_connect(&self, timeout: Duration) -> Result<(), Error> {
         // Check if relay can't connect
         if !self.status().can_connect() {
@@ -304,7 +326,9 @@ impl Relay {
         Ok(())
     }
 
-    /// Disconnect from relay and set status to 'Terminated'
+    /// Disconnect from relay and set status to [`RelayStatus::Terminated`].
+    ///
+    /// Returns immediately if the status is already [`RelayStatus::Terminated`].
     #[inline]
     pub fn disconnect(&self) {
         self.inner.disconnect()

crates/nostr-sdk/src/client/mod.rs

@@ -437,6 +437,14 @@ impl Client {
     }
 
     /// Connect to all added relays
+    ///
+    /// Attempts to initiate a connection for every relay currently in
+    /// [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`].
+    /// A background connection task is spawned for each such relay, which then tries
+    /// to establish the connection.
+    /// Any relay not in one of these two statuses is skipped.
+    ///
+    /// For further details, see the documentation of [`Relay::connect`].
     #[inline]
     pub async fn connect(&self) {
         self.pool.connect().await;
@@ -453,12 +461,14 @@ impl Client {
 
     /// Try to establish a connection with the relays.
     ///
-    /// Attempts to establish a connection without spawning the connection task if it fails.
+    /// Attempts to establish a connection for every relay currently in
+    /// [`RelayStatus::Initialized`] or [`RelayStatus::Terminated`]
+    /// without spawning the connection task if it fails.
     /// This means that if the connection fails, no automatic retries are scheduled.
     /// Use [`Client::connect`] if you want to immediately spawn a connection task,
     /// regardless of whether the initial connection succeeds.
     ///
-    /// For further details, see the documentation of [`RelayPool::try_connect`].
+    /// For further details, see the documentation of [`Relay::try_connect`].
     #[inline]
     pub async fn try_connect(&self, timeout: Duration) -> Output<()> {
         self.pool.try_connect(timeout).await