Fix minor broken doc links and add missing feature flag (#1471)

* Fix minor broken doc links and add missing feature flag

Signed-off-by: clux <[email protected]>

* suggestion + another broken link

Signed-off-by: clux <[email protected]>

---------

Signed-off-by: clux <[email protected]>

kube-runtime/src/reflector/mod.rs

@@ -17,7 +17,7 @@ pub use store::{store, Store};
 
 /// Cache objects from a [`watcher()`] stream into a local [`Store`]
 ///
-/// Observes the raw [`Stream`] of [`watcher::Event`] objects, and modifies the cache.
+/// Observes the raw `Stream` of [`watcher::Event`] objects, and modifies the cache.
 /// It passes the raw [`watcher()`] stream through unmodified.
 ///
 /// ## Usage
@@ -98,6 +98,21 @@ pub use store::{store, Store};
 /// Additionally, only `labels`, `annotations` and `managed_fields` are safe to drop from `ObjectMeta`.
 ///
 /// For more information check out: <https://kube.rs/controllers/optimization/> for graphs and techniques.
+///
+/// ## Stream sharing
+///
+/// `reflector()` as an interface may optionally create a stream that can be
+/// shared with other components to help with resource usage.
+///
+/// To share a stream, the `Writer<K>` consumed by `reflector()` must be
+/// created through an interface that allows a store to be subscribed on, such
+/// as [`store_shared()`]. When the store supports being subscribed on, it will
+/// broadcast an event to all active listeners after caching any object
+/// contained in the event.
+///
+/// Creating subscribers requires an
+/// [`unstable`](https://github.com/kube-rs/kube/blob/main/kube-runtime/Cargo.toml#L17-L21)
+/// feature
 pub fn reflector<K, W>(mut writer: store::Writer<K>, stream: W) -> impl Stream<Item = W::Item>
 where
     K: Lookup + Clone,

kube-runtime/src/reflector/store.rs

@@ -83,6 +83,10 @@ where
     ///
     /// Multiple subscribe handles may be obtained, by either calling
     /// `subscribe` multiple times, or by calling `clone()`
+    ///
+    /// This function returns a `Some` when the [`Writer`] is constructed through
+    /// [`Writer::new_shared`] or [`store_shared`], and a `None` otherwise.
+    #[cfg(feature = "unstable-runtime-subscribe")]
     pub fn subscribe(&self) -> Option<ReflectHandle<K>> {
         self.dispatcher
             .as_ref()

kube-runtime/src/scheduler.rs

@@ -1,4 +1,4 @@
-//! Delays and deduplicates [`Stream`] items
+//! Delays and deduplicates [`Stream`](futures::stream::Stream) items
 
 use futures::{stream::Fuse, Stream, StreamExt};
 use hashbrown::{hash_map::Entry, HashMap};
@@ -251,7 +251,7 @@ where
     }
 }
 
-/// Stream transformer that delays and deduplicates [`Stream`] items.
+/// Stream transformer that delays and deduplicates items.
 ///
 /// Items are deduplicated: if an item is submitted multiple times before being emitted then it will only be
 /// emitted at the earliest `Instant`.

kube-runtime/src/utils/watch_ext.rs

@@ -277,6 +277,8 @@ pub trait WatchStreamExt: Stream {
     ///
     ///
     /// [`Store`]: crate::reflector::Store
+    /// [`subscribe()`]: crate::reflector::store::Writer::subscribe()
+    /// [`Stream`]: futures::stream::Stream
     /// [`ReflectHandle`]: crate::reflector::dispatcher::ReflectHandle
     /// ## Usage
     /// ```no_run