doc(storage): recommend using WithJSONReads (googleapis#10331)

Update docs to recommend using the JSON API for downloads over XML, and note that we will switch the default to JSON at some point.

Fixes googleapis#9763

storage/option.go

@@ -44,10 +44,14 @@ type storageClientOption interface {
 	ApplyStorageOpt(*storageConfig)
 }
 
-// WithJSONReads is an option that may be passed to a Storage Client on creation.
-// It sets the client to use the JSON API for object reads. Currently, the
-// default API used for reads is XML.
-// Setting this option is required to use the GenerationNotMatch condition.
+// WithJSONReads is an option that may be passed to [NewClient].
+// It sets the client to use the Cloud Storage JSON API for object
+// reads. Currently, the default API used for reads is XML, but JSON will
+// become the default in a future release.
+//
+// Setting this option is required to use the GenerationNotMatch condition. We
+// also recommend using JSON reads to ensure consistency with other client
+// operations (all of which use JSON by default).
 //
 // Note that when this option is set, reads will return a zero date for
 // [ReaderObjectAttrs].LastModified and may return a different value for
@@ -56,10 +60,11 @@ func WithJSONReads() option.ClientOption {
 	return &withReadAPI{useJSON: true}
 }
 
-// WithXMLReads is an option that may be passed to a Storage Client on creation.
-// It sets the client to use the XML API for object reads.
+// WithXMLReads is an option that may be passed to [NewClient].
+// It sets the client to use the Cloud Storage XML API for object reads.
 //
-// This is the current default.
+// This is the current default, but the default will switch to JSON in a future
+// release.
 func WithXMLReads() option.ClientOption {
 	return &withReadAPI{useJSON: false}
 }

storage/reader.go

@@ -72,6 +72,12 @@ type ReaderObjectAttrs struct {
 // ErrObjectNotExist will be returned if the object is not found.
 //
 // The caller must call Close on the returned Reader when done reading.
+//
+// By default, reads are made using the Cloud Storage XML API. We recommend
+// using the JSON API instead, which can be done by setting [WithJSONReads]
+// when calling [NewClient]. This ensures consistency with other client
+// operations, which all use JSON. JSON will become the default in a future
+// release.
 func (o *ObjectHandle) NewReader(ctx context.Context) (*Reader, error) {
 	return o.NewRangeReader(ctx, 0, -1)
 }
@@ -86,6 +92,12 @@ func (o *ObjectHandle) NewReader(ctx context.Context) (*Reader, error) {
 // decompressive transcoding per https://cloud.google.com/storage/docs/transcoding
 // that file will be served back whole, regardless of the requested range as
 // Google Cloud Storage dictates.
+//
+// By default, reads are made using the Cloud Storage XML API. We recommend
+// using the JSON API instead, which can be done by setting [WithJSONReads]
+// when calling [NewClient]. This ensures consistency with other client
+// operations, which all use JSON. JSON will become the default in a future
+// release.
 func (o *ObjectHandle) NewRangeReader(ctx context.Context, offset, length int64) (r *Reader, err error) {
 	// This span covers the life of the reader. It is closed via the context
 	// in Reader.Close.