add some docs to distinguish the ext method block from the ctor block

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

kube-client/Cargo.toml

@@ -34,7 +34,7 @@ unstable-client = []
 __non_core = ["tracing", "serde_yaml", "base64"]
 
 [package.metadata.docs.rs]
-features = ["client", "rustls-tls", "openssl-tls", "ws", "oauth", "oidc", "jsonpatch", "admission", "k8s-openapi/latest", "socks5"]
+features = ["client", "rustls-tls", "openssl-tls", "ws", "oauth", "oidc", "jsonpatch", "admission", "k8s-openapi/latest", "socks5", "unstable-client"]
 # Define the configuration attribute `docsrs`. Used to enable `doc_cfg` feature.
 rustdoc-args = ["--cfg", "docsrs"]
 

kube-client/src/client/client_ext.rs

@@ -123,16 +123,38 @@ pub enum NamespaceError {
     MissingName,
 }
 
-/// Client extensions to allow typed api calls without [`Api`]
+/// Generic client extensions for the `unstable-client` feature
 ///
 /// These methods allow users to query across a wide-array of resources without needing
-/// to explicitly create an `Api` for each one of them.
+/// to explicitly create an [`Api`](crate::Api) for each one of them.
 ///
-/// The tradeoff is that you need to explicitly:
-/// - specify the level you are querying at via [`Cluster`] or [`Namespace`] as args
-/// - specify the resource type you are using for serialization (e.g. a top level k8s-openapi type)
+/// ## Usage
+/// 1. Create a [`Client`]
+/// 2. Specify the level you are querying at via [`Cluster`] or [`Namespace`] as args
+/// 3. Specify the resource type you are using for serialization (e.g. a top level k8s-openapi type)
+///
+/// ## Example
+///
+/// ```no_run
+/// # use k8s_openapi::api::core::v1::Pod;
+/// # use k8s_openapi::api::core::v1::Service;
+/// # use kube::client::{Cluster, Namespace};
+/// # use kube::{ResourceExt, api::ListParams};
+/// # async fn wrapper() -> Result<(), Box<dyn std::error::Error>> {
+/// # let client: kube::Client = todo!();
+/// let lp = ListParams::default();
+/// # List at cluster level:
+/// for pod in client.list::<Pod>(&lp, &Cluster).await? {
+///     println!("Found pod {} in {}", pod.name_any(), pod.namespace().unwrap());
+/// }
+/// # Namespaced get:
+/// let svc = client.get::<Service>("kubernetes", &Namespace::from("default")).await?;
+/// assert_eq!(svc.name_unchecked(), "kubernetes");
+/// # Ok(())
+/// # }
+/// ```
 impl Client {
-    /// Get a resource
+    /// Get a single instance of a `Resource` implementing type `K` at the specified scope.
     ///
     /// ```no_run
     /// # use k8s_openapi::api::rbac::v1::ClusterRole;
@@ -160,7 +182,7 @@ impl Client {
         self.request::<K>(req).await
     }
 
-    /// List a resource
+    /// List instances of a `Resource` implementing type `K` at the specified scope.
     ///
     /// ```no_run
     /// # use k8s_openapi::api::core::v1::Pod;

kube-client/src/client/mod.rs

@@ -77,6 +77,11 @@ pub struct Client {
     default_ns: String,
 }
 
+/// Constructors and low-level api interfaces.
+///
+/// Most users only need [`Client::try_default`] or [`Client::new`] from this block.
+///
+/// The many various lower level interfaces here are for more advanced use-cases with specific requirements.
 impl Client {
     /// Create a [`Client`] using a custom `Service` stack.
     ///
@@ -131,6 +136,14 @@ impl Client {
     ///
     /// Will fail if neither configuration could be loaded.
     ///
+    /// ```rust
+    /// # async fn doc() -> Result<(), Box<dyn std::error::Error>> {
+    /// # use kube::Client;
+    /// let client = Client::try_default().await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    ///
     /// If you already have a [`Config`] then use [`Client::try_from`](Self::try_from)
     /// instead.
     pub async fn try_default() -> Result<Self> {
@@ -468,7 +481,9 @@ fn handle_api_errors(text: &str, s: StatusCode) -> Result<()> {
 impl TryFrom<Config> for Client {
     type Error = Error;
 
-    /// Builds a default [`Client`] from a [`Config`], see [`ClientBuilder`] if more customization is required
+    /// Builds a default [`Client`] from a [`Config`].
+    ///
+    /// See [`ClientBuilder`] or [`Client::new`] if more customization is required
     fn try_from(config: Config) -> Result<Self> {
         Ok(ClientBuilder::try_from(config)?.build())
     }