📖 Fix Client Read/Write Functionality Comments

pkg/client/client.go

@@ -90,11 +90,18 @@ type CacheOptions struct {
 type NewClientFunc func(config *rest.Config, options Options) (Client, error)
 
 // New returns a new Client using the provided config and Options.
-// The returned client reads *and* writes directly from the server
-// (it doesn't use object caches).  It understands how to work with
-// normal types (both custom resources and aggregated/built-in resources),
-// as well as unstructured types.
 //
+// The client's read behavior is determined by Options.Cache.
+// If either Options.Cache or Options.Cache.Reader is nil,
+// the client reads directly from the API server.
+// If both Options.Cache and Options.Cache.Reader are non-nil,
+// the client reads from a local cache. However, specific
+// resources can still be configured to bypass the cache based
+// on Options.Cache.Unstructured and Options.Cache.DisableFor.
+// Write operations are always performed directly on the API server.
+//
+// The client understands how to work with normal types (both custom resources
+// and aggregated/built-in resources), as well as unstructured types.
 // In the case of normal types, the scheme will be used to look up the
 // corresponding group, version, and kind for the given type.  In the
 // case of unstructured types, the group, version, and kind will be extracted
@@ -210,7 +217,8 @@ func newClient(config *rest.Config, options Options) (*client, error) {
 
 var _ Client = &client{}
 
-// client is a client.Client that reads and writes directly from/to an API server.
+// client is a client.Client configured to either read from a local cache or directly from the API server.
+// Write operations are always performed directly on the API server.
 // It lazily initializes new clients at the time they are used.
 type client struct {
 	typedClient        typedClient