better docs and links between for Api::watch and watcher

kube-runtime/src/watcher.rs

@@ -181,10 +181,39 @@ async fn step<K: Meta + Clone + DeserializeOwned + Send + 'static>(
     }
 }
 
-/// Watches a Kubernetes Resource for changes
+/// Watches a Kubernetes Resource for changes continuously
 ///
-/// Errors are propagated to the client as `Err`. Tries to recover (by reconnecting and resyncing as required)
-/// if polled again after an error.
+/// Creates an indefinite read stream through continual [`Api::watch`] calls, and keeping track
+/// of [returned resource versions](https://kubernetes.io/docs/reference/using-api/api-concepts/#efficient-detection-of-changes).
+/// It tries to recover (by reconnecting and resyncing as required) if polled again after an error.
+/// However, keep in mind that most terminal `TryStream` combinators (such as `TryFutureExt::try_for_each`
+/// and `TryFutureExt::try_concat` will terminate eagerly if an `Error` reaches them.
+///
+/// This is intended to provide a safe and atomic input interface for a state store like a [`reflector`],
+/// direct users may want to flatten composite events with [`try_flatten_applied`]:
+///
+/// ```no_run
+/// use kube::{api::{Api, ListParams, Meta}, Client};
+/// use kube_runtime::{utils::try_flatten_applied, watcher};
+/// use k8s_openapi::api::core::v1::Pod;
+/// use futures::{StreamExt, TryStreamExt};
+/// #[tokio::main]
+/// async fn main() -> Result<(), kube_runtime::watcher::Error> {
+///     let client = Client::try_default().await.unwrap();
+///     let pods: Api<Pod> = Api::namespaced(client, "apps");
+///     let watcher = watcher(pods, ListParams::default());
+///     try_flatten_applied(watcher)
+///         .try_for_each(|p| async move {
+///          println!("Applied: {}", Meta::name(&p));
+///             Ok(())
+///         })
+///         .await?;
+///    Ok(())
+/// }
+/// ```
+/// [`try_flatten_applied`]: super::utils::try_flatten_applied
+/// [`reflector`]: super::reflector::reflector
+/// [`Api::watch`]: https://docs.rs/kube/*/kube/struct.Api.html#method.watch
 ///
 /// # Migration from `kube::runtime`
 ///

kube/src/api/typed.rs

@@ -293,6 +293,12 @@ where
     /// This returns a future that awaits the initial response,
     /// then you can stream the remaining buffered `WatchEvent` objects.
     ///
+    /// Note that a `watch` call can terminate for many reasons (even before the specified
+    /// [`ListParams::timeout`] is triggered), and will have to be re-issued
+    /// with the last seen resource version when or if it closes.
+    ///
+    /// Consider using a managed [`watcher`] to deal with automatic re-watches and error cases.
+    ///
     /// ```no_run
     /// use kube::{api::{Api, ListParams, Meta, WatchEvent}, Client};
     /// use k8s_openapi::api::batch::v1::Job;
@@ -317,6 +323,8 @@ where
     ///     Ok(())
     /// }
     /// ```
+    /// [`ListParams::timeout`]: super::ListParams::timeout
+    /// [`watcher`]: https://docs.rs/kube_runtime/*/kube_runtime/watcher/fn.watcher.html
     pub async fn watch(
         &self,
         lp: &ListParams,