Fix doc warnings

Signed-off-by: Natalie Klestrup Röijezon <[email protected]>

kube-client/src/api/mod.rs

@@ -60,7 +60,7 @@ pub struct Api<K> {
 
 /// Api constructors for Resource implementors with custom DynamicTypes
 ///
-/// This generally means resources created via [`DynamicObject`](crate::api::DynamicObject).
+/// This generally means resources created via [`DynamicObject`].
 impl<K: Resource> Api<K> {
     /// Cluster level resources, or resources viewed across all namespaces
     ///

kube-client/src/api/subresource.rs

@@ -451,7 +451,7 @@ fn evict_path() {
 
 /// Marker trait for objects that can be evicted
 ///
-/// See [`Api::evic`] for usage
+/// See [`Api::evict`] for usage
 pub trait Evict {}
 
 impl Evict for k8s_openapi::api::core::v1::Pod {}

kube-client/src/client/mod.rs

@@ -88,8 +88,7 @@ pub struct Client {
 impl Client {
     /// Create a [`Client`] using a custom `Service` stack.
     ///
-    /// [`ConfigExt`](crate::client::ConfigExt) provides extensions for
-    /// building a custom stack.
+    /// [`ConfigExt`] provides extensions for building a custom stack.
     ///
     /// To create with the default stack with a [`Config`], use
     /// [`Client::try_from`].

kube-client/src/config/file_config.rs

@@ -115,7 +115,7 @@ pub struct Cluster {
     /// `disable_compression` allows client to opt-out of response compression for all requests to the server.
     /// This is useful to speed up requests (specifically lists) when client-server network bandwidth is ample,
     /// by saving time on compression (server-side) and decompression (client-side):
-    /// https://github.com/kubernetes/kubernetes/issues/112296
+    /// <https://github.com/kubernetes/kubernetes/issues/112296>
     #[serde(rename = "disable-compression")]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub disable_compression: Option<bool>,
@@ -550,7 +550,7 @@ impl AuthInfo {
 
 /// Connection information for auth plugins that have `provideClusterInfo` enabled.
 ///
-/// This is a copy of [`kube::config::Cluster`] with certificate_authority passed as bytes without the path.
+/// This is a copy of [`Cluster`] with certificate_authority passed as bytes without the path.
 /// Taken from [clientauthentication/types.go#Cluster](https://github.com/kubernetes/client-go/blob/477cb782cf024bc70b7239f0dca91e5774811950/pkg/apis/clientauthentication/types.go#L73-L129)
 #[derive(Clone, Debug, Serialize, Deserialize, Default)]
 #[serde(rename_all = "kebab-case")]

kube-client/src/discovery/mod.rs

@@ -45,7 +45,7 @@ impl DiscoveryMode {
 /// To make use of discovered apis, extract one or more [`ApiGroup`]s from it,
 /// or resolve a precise one using [`Discovery::resolve_gvk`](crate::discovery::Discovery::resolve_gvk).
 ///
-/// If caching of results is __not required__, then a simpler [`oneshot`](crate::discovery::oneshot) discovery system can be used.
+/// If caching of results is __not required__, then a simpler [`oneshot`] discovery system can be used.
 ///
 /// [`ApiGroup`]: crate::discovery::ApiGroup
 #[cfg_attr(docsrs, doc(cfg(feature = "client")))]

kube-client/src/lib.rs

@@ -56,9 +56,9 @@
 //!
 //! For more details, see:
 //!
-//! - [`Client`](crate::client) for the extensible Kubernetes client
-//! - [`Config`](crate::config) for the Kubernetes config abstraction
-//! - [`Api`](crate::Api) for the generic api methods available on Kubernetes resources
+//! - [`client`] for the extensible Kubernetes client
+//! - [`config`] for the Kubernetes config abstraction
+//! - [`Api`] for the generic api methods available on Kubernetes resources
 //! - [k8s-openapi](https://docs.rs/k8s-openapi) for how to create typed kubernetes objects directly
 #![cfg_attr(docsrs, feature(doc_cfg))]
 // Nightly clippy (0.1.64) considers Drop a side effect, see https://github.com/rust-lang/rust-clippy/issues/9608

kube-core/src/object.rs

@@ -13,9 +13,9 @@ use std::borrow::Cow;
 /// Kubernetes' API [always seem to expose list structs in this manner](https://docs.rs/k8s-openapi/0.10.0/k8s_openapi/apimachinery/pkg/apis/meta/v1/struct.ObjectMeta.html?search=List).
 ///
 /// Note that this is only used internally within reflectors and informers,
-/// and is generally produced from list/watch/delete collection queries on an [`Resource`](super::Resource).
+/// and is generally produced from list/watch/delete collection queries on an [`Resource`].
 ///
-/// This is almost equivalent to [`k8s_openapi::List<T>`](k8s_openapi::List), but iterable.
+/// This is almost equivalent to [`k8s_openapi::List<T>`], but iterable.
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct ObjectList<T>
 where
@@ -27,7 +27,7 @@ where
 
     /// ListMeta - only really used for its `resourceVersion`
     ///
-    /// See [ListMeta](k8s_openapi::apimachinery::pkg::apis::meta::v1::ListMeta)
+    /// See [ListMeta]
     #[serde(default)]
     pub metadata: ListMeta,
 
@@ -312,7 +312,7 @@ where
 /// Empty struct for when data should be discarded
 ///
 /// Not using [`()`](https://doc.rust-lang.org/stable/std/primitive.unit.html), because serde's
-/// [`Deserialize`](serde::Deserialize) `impl` is too strict.
+/// [`Deserialize`] `impl` is too strict.
 #[derive(Clone, Deserialize, Serialize, Default, Debug)]
 pub struct NotUsed {}
 

kube-core/src/params.rs

@@ -168,7 +168,7 @@ impl ListParams {
 
     /// Configure typed label selectors
     ///
-    /// Configure typed selectors from [`Selector`](crate::Selector) and [`Expression`](crate::Expression) lists.
+    /// Configure typed selectors from [`Selector`] and [`Expression`](crate::Expression) lists.
     ///
     /// ```
     /// use kube::core::{Expression, Selector, ParseExpressionError};
@@ -456,7 +456,7 @@ impl WatchParams {
 
     /// Configure typed label selectors
     ///
-    /// Configure typed selectors from [`Selector`](crate::Selector) and [`Expression`](crate::Expression) lists.
+    /// Configure typed selectors from [`Selector`] and [`Expression`](crate::Expression) lists.
     ///
     /// ```
     /// use kube::core::{Expression, Selector, ParseExpressionError};

kube-derive/src/lib.rs

@@ -365,8 +365,8 @@ pub fn derive_custom_resource(input: proc_macro::TokenStream) -> proc_macro::Tok
 /// ```
 ///
 /// The example above will generate:
-/// ```
-/// // impl kube::Resource for FooMap { .. }
+/// ```rust,ignore
+/// impl kube::Resource for FooMap { .. }
 /// ```
 /// [`kube`]: https://docs.rs/kube
 /// [`kube::Api`]: https://docs.rs/kube/*/kube/struct.Api.html

kube-runtime/src/controller/mod.rs

@@ -915,7 +915,7 @@ where
     ///
     /// This includes the core watch, as well as auxilary watches introduced by [`Self::owns`] and [`Self::watches`].
     ///
-    /// The [`default_backoff`](crate::watcher::default_backoff) follows client-go conventions,
+    /// The [default backoff policy](crate::WatchStreamExt::default_backoff) follows client-go conventions,
     /// but can be overridden by calling this method.
     #[must_use]
     pub fn trigger_backoff(mut self, backoff_builder: impl BackoffBuilder + Clone + 'static) -> Self {

kube-runtime/src/reflector/dispatcher.rs

@@ -14,6 +14,8 @@ use async_broadcast::{InactiveReceiver, Receiver, Sender};
 
 use super::Lookup;
 
+#[cfg(doc)] pub use super::store::Writer;
+
 #[derive(Educe)]
 #[educe(Debug(bound("K: Debug, K::DynamicType: Debug")), Clone)]
 // A helper type that holds a broadcast transmitter and a broadcast receiver,
@@ -74,18 +76,16 @@ where
 
 /// A handle to a shared stream reader
 ///
-/// [`ReflectHandle`]s are created by calling [`subscribe()`] on a [`Writer`],
-/// or by calling `clone()` on an already existing [`ReflectHandle`]. Each
-/// shared stream reader should be polled independently and driven to readiness
+/// [`ReflectHandle`]s are created by calling [`Writer::subscribe`],
+/// or by calling [`clone`](Clone::clone) on an already existing [`ReflectHandle`].
+/// Each shared stream reader should be polled independently and driven to readiness
 /// to avoid deadlocks. When the [`Writer`]'s buffer is filled, backpressure
 /// will be applied on the root stream side.
 ///
 /// When the root stream is dropped, or it ends, all [`ReflectHandle`]s
 /// subscribed to the stream will also terminate after all events yielded by
 /// the root stream have been observed. This means [`ReflectHandle`] streams
 /// can still be polled after the root stream has been dropped.
-///
-/// [`Writer`]: crate::reflector::Writer
 #[pin_project]
 pub struct ReflectHandle<K>
 where

kube-runtime/src/reflector/object_ref.rs

@@ -28,7 +28,7 @@ pub trait Lookup {
     /// The [version](Resource::version) for this object.
     fn version(dyntype: &Self::DynamicType) -> Cow<'_, str>;
 
-    /// The [apiVersion](Resource::_version) for this object.
+    /// The [apiVersion](Resource::api_version) for this object.
     fn api_version(dyntype: &Self::DynamicType) -> Cow<'_, str> {
         api_version_from_group_version(Self::group(dyntype), Self::version(dyntype))
     }

kube-runtime/src/scheduler.rs

@@ -1,4 +1,4 @@
-//! Delays and deduplicates [`Stream`](futures::stream::Stream) items
+//! Delays and deduplicates [`Stream`] items
 
 use futures::{stream::Fuse, Stream, StreamExt};
 use hashbrown::{hash_map::RawEntryMut, HashMap};

kube-runtime/src/utils/backoff_reset_timer.rs

@@ -4,6 +4,8 @@ use backon::BackoffBuilder;
 
 use super::{ResettableBackoff, ResettableBackoffWrapper};
 
+#[cfg(doc)] use backon::Backoff;
+
 /// Builder for [`ResetTimerBackoff`].
 #[derive(Debug, Clone)]
 pub struct ResetTimerBackoffBuilder<B> {

kube-runtime/src/utils/stream_backoff.rs

@@ -6,12 +6,14 @@ use tokio::time::{sleep, Instant, Sleep};
 
 use super::ResettableBackoff;
 
+#[cfg(doc)] use backon::Backoff;
+
 /// Applies a [`Backoff`] policy to a [`Stream`]
 ///
-/// After any [`Err`] is emitted, the stream is paused for [`Backoff::next_backoff`]. The
-/// [`Backoff`] is [`reset`](`Backoff::reset`) on any [`Ok`] value.
+/// After any [`Err`] is emitted, the stream is paused for [`Backoff::next`](Iterator::next). The
+/// [`Backoff`] is [`reset`](`ResettableBackoff::reset`) on any [`Ok`] value.
 ///
-/// If [`Backoff::next_backoff`] returns [`None`] then the backing stream is given up on, and closed.
+/// If [`Backoff::next`](Iterator::next) returns [`None`] then the backing stream is given up on, and closed.
 #[pin_project]
 pub struct StreamBackoff<S, B> {
     #[pin]

kube-runtime/src/utils/watch_ext.rs

@@ -16,7 +16,10 @@ use futures::{Stream, TryStream};
 
 use super::ResettableBackoffWrapper;
 
-/// Extension trait for streams returned by [`watcher`](watcher()) or [`reflector`](crate::reflector::reflector)
+#[cfg(doc)] use crate::watcher::DefaultBackoff;
+#[cfg(doc)] use backon::Backoff;
+
+/// Extension trait for streams returned by [`watcher`](watcher::watcher) or [`reflector`](crate::reflector::reflector)
 pub trait WatchStreamExt: Stream {
     /// Apply the [`DefaultBackoff`] watcher [`Backoff`] policy
     ///
@@ -40,6 +43,8 @@ pub trait WatchStreamExt: Stream {
     /// Decode a [`watcher()`] stream into a stream of applied objects
     ///
     /// All Added/Modified events are passed through, and critical errors bubble up.
+    ///
+    /// [`watcher()`]: crate::watcher::watcher
     fn applied_objects<K>(self) -> EventDecode<Self>
     where
         Self: Stream<Item = Result<watcher::Event<K>, watcher::Error>> + Sized,
@@ -50,6 +55,8 @@ pub trait WatchStreamExt: Stream {
     /// Decode a [`watcher()`] stream into a stream of touched objects
     ///
     /// All Added/Modified/Deleted events are passed through, and critical errors bubble up.
+    ///
+    /// [`watcher()`]: crate::watcher::watcher
     fn touched_objects<K>(self) -> EventDecode<Self>
     where
         Self: Stream<Item = Result<watcher::Event<K>, watcher::Error>> + Sized,
@@ -84,6 +91,8 @@ pub trait WatchStreamExt: Stream {
     /// # Ok(())
     /// # }
     /// ```
+
+    /// [`watcher()`]: crate::watcher::watcher
     fn modify<F, K>(self, f: F) -> EventModify<Self, F>
     where
         Self: Stream<Item = Result<watcher::Event<K>, watcher::Error>> + Sized,
@@ -173,6 +182,7 @@ pub trait WatchStreamExt: Stream {
     /// ```
     ///
     /// [`Store`]: crate::reflector::Store
+    /// [`watcher()`]: crate::watcher::watcher
     fn reflect<K>(self, writer: Writer<K>) -> Reflect<Self, K>
     where
         Self: Stream<Item = watcher::Result<watcher::Event<K>>> + Sized,
@@ -187,7 +197,7 @@ pub trait WatchStreamExt: Stream {
     /// Returns the stream unmodified, but passes every [`watcher::Event`]
     /// through a [`Writer`]. This populates a [`Store`] as the stream is
     /// polled. When the [`watcher::Event`] is not an error or a
-    /// [`watcher::Event::Deleted`] then its inner object will also be
+    /// [`watcher::Event::Delete`] then its inner object will also be
     /// propagated to subscribers.
     ///
     /// Subscribers can be created by calling [`subscribe()`] on a [`Writer`].
@@ -212,7 +222,9 @@ pub trait WatchStreamExt: Stream {
     /// [`Store`]: crate::reflector::Store
     /// [`subscribe()`]: crate::reflector::store::Writer::subscribe()
     /// [`Stream`]: futures::stream::Stream
-    /// [`ReflectHandle`]: crate::reflector::dispatcher::ReflectHandle
+    /// [`ReflectHandle`]: crate::reflector::ReflectHandle
+    /// [`watcher()`]: crate::watcher::watcher
+    ///
     /// ## Usage
     /// ```no_run
     /// # use futures::StreamExt;

kube-runtime/src/watcher.rs

@@ -18,6 +18,9 @@ use std::{clone::Clone, collections::VecDeque, fmt::Debug, future, time::Duratio
 use thiserror::Error;
 use tracing::{debug, error, warn};
 
+#[cfg(doc)] use crate::WatchStreamExt;
+#[cfg(doc)] use backon::Backoff;
+
 #[derive(Debug, Error)]
 pub enum Error {
     #[error("failed to perform initial object list: {0}")]
@@ -43,26 +46,27 @@ pub enum Event<K> {
     /// NOTE: This should not be used for managing persistent state elsewhere, since
     /// events may be lost if the watcher is unavailable. Use Finalizers instead.
     Delete(K),
+
     /// The watch stream was restarted.
     ///
-    /// A series of `InitApply` events are expected to follow until all matching objects
+    /// A series of [`InitApply`](Event::InitApply) events will follow until all matching objects
     /// have been listed. This event can be used to prepare a buffer for `InitApply` events.
     Init,
-    /// Received an object during `Init`.
+    /// Received an object during [`Init`](Event::Init).
     ///
-    /// Objects returned here are either from the initial stream using the `StreamingList` strategy,
-    /// or from pages using the `ListWatch` strategy.
+    /// Objects returned here are either from the initial stream using the [`InitialListStrategy::StreamingList`] strategy,
+    /// or from pages using the [`InitialListStrategy::ListWatch`] strategy.
     ///
     /// These events can be passed up if having a complete set of objects is not a concern.
-    /// If you need to wait for a complete set, please buffer these events until an `InitDone`.
+    /// If you need to wait for a complete set, please buffer these events until an [`InitDone`](Event::InitDone).
     InitApply(K),
     /// The initialisation is complete.
     ///
     /// This can be used as a signal to replace buffered store contents atomically.
-    /// No more `InitApply` events will happen until the next `Init` event.
+    /// No more [`InitApply`](Event::InitApply) events will happen until the next [`Init`](Event::Init) event.
     ///
-    /// Any objects that were previously [`Applied`](Event::Applied) but are not listed in any of
-    /// the `InitApply` events should be assumed to have been [`Deleted`](Event::Deleted).
+    /// Any objects that were previously [`Apply`ed](Event::Apply) but are not listed in any of
+    /// the [`InitApply`](Event::InitApply) events should be assumed to have been [`Delete`d](Event::Delete).
     InitDone,
 }
 
@@ -339,7 +343,7 @@ impl Config {
 
     /// Configure typed label selectors
     ///
-    /// Configure typed selectors from [`Selector`](kube_client::core::Selector) and [`Expression`](kube_client::core::Expression) lists.
+    /// Configure typed selectors from [`Selector`] and [`Expression`](kube_client::core::Expression) lists.
     ///
     /// ```
     /// use kube_runtime::watcher::Config;
@@ -748,7 +752,7 @@ where
 ///
 /// The stream will attempt to be recovered on the next poll after an [`Err`] is returned.
 /// This will normally happen immediately, but you can use [`StreamBackoff`](crate::utils::StreamBackoff)
-/// to introduce an artificial delay. [`default_backoff`] returns a suitable default set of parameters.
+/// to introduce an artificial delay. [`WatchStreamExt::default_backoff`] returns a suitable default set of parameters.
 ///
 /// If the watch connection is interrupted, then `watcher` will attempt to restart the watch using the last
 /// [resource version](https://kubernetes.io/docs/reference/using-api/api-concepts/#efficient-detection-of-changes)
@@ -811,7 +815,7 @@ pub fn watcher<K: Resource + Clone + DeserializeOwned + Debug + Send + 'static>(
 ///
 /// The stream will attempt to be recovered on the next poll after an [`Err`] is returned.
 /// This will normally happen immediately, but you can use [`StreamBackoff`](crate::utils::StreamBackoff)
-/// to introduce an artificial delay. [`default_backoff`] returns a suitable default set of parameters.
+/// to introduce an artificial delay. [`WatchStreamExt::default_backoff`] returns a suitable default set of parameters.
 ///
 /// If the watch connection is interrupted, then `watcher` will attempt to restart the watch using the last
 /// [resource version](https://kubernetes.io/docs/reference/using-api/api-concepts/#efficient-detection-of-changes)