docs(storage): add preview comment to NewMultiRangeDownloader (#11420)

* docs(storage): add preview comment to NewMultiRangeDownloader

* Add preview note to append

storage/reader.go

@@ -158,6 +158,10 @@ func (o *ObjectHandle) NewRangeReader(ctx context.Context, offset, length int64)
 }
 
 // NewMultiRangeDownloader creates a multi-range reader for an object.
+// Must be called on a gRPC client created using [NewGRPCClient].
+//
+// This uses the gRPC-specific bi-directional read API, which is in private
+// preview; please contact your account manager if interested.
 func (o *ObjectHandle) NewMultiRangeDownloader(ctx context.Context) (mrd *MultiRangeDownloader, err error) {
 	// This span covers the life of the reader. It is closed via the context
 	// in Reader.Close.
@@ -344,8 +348,24 @@ func (r *Reader) LastModified() (time.Time, error) {
 	return r.Attrs.LastModified, nil
 }
 
+// Metadata returns user-provided metadata, in key/value pairs.
+//
+// It can be nil if no metadata is present, or if the client uses the JSON
+// API for downloads. Only the XML and gRPC APIs support getting
+// custom metadata via the Reader; for JSON make a separate call to
+// ObjectHandle.Attrs.
+func (r *Reader) Metadata() map[string]string {
+	if r.objectMetadata != nil {
+		return *r.objectMetadata
+	}
+	return nil
+}
+
 // ReadHandle returns the read handle associated with an object.
-// Read Handle will be periodically refreshed.
+// ReadHandle will be periodically refreshed.
+//
+// ReadHandle requires the gRPC-specific bi-directional read API, which is in
+// private preview; please contact your account manager if interested.
 // Note that this only valid for gRPC and only with zonal buckets.
 func (r *Reader) ReadHandle() ReadHandle {
 	if r.handle == nil {
@@ -360,6 +380,8 @@ func (r *Reader) ReadHandle() ReadHandle {
 //
 // Typically, a MultiRangeDownloader opens a stream to which we can add
 // different ranges to read from the object.
+//
+// This API is currently in preview and is not yet available for general use.
 type MultiRangeDownloader struct {
 	Attrs  ReaderObjectAttrs
 	reader multiRangeDownloader
@@ -398,6 +420,7 @@ func (mrd *MultiRangeDownloader) Add(output io.Writer, offset, length int64, cal
 //
 // This will immediately close the stream and can result in a
 // "stream closed early" error if a response for a range is still not processed.
+// Call [MultiRangeDownloader.Wait] to avoid this error.
 func (mrd *MultiRangeDownloader) Close() error {
 	err := mrd.reader.close()
 	trace.EndSpan(mrd.ctx, err)
@@ -416,16 +439,3 @@ func (mrd *MultiRangeDownloader) Wait() {
 func (mrd *MultiRangeDownloader) GetHandle() []byte {
 	return mrd.reader.getHandle()
 }
-
-// Metadata returns user-provided metadata, in key/value pairs.
-//
-// It can be nil if no metadata is present, or if the client uses the JSON
-// API for downloads. Only the XML and gRPC APIs support getting
-// custom metadata via the Reader; for JSON make a separate call to
-// ObjectHandle.Attrs.
-func (r *Reader) Metadata() map[string]string {
-	if r.objectMetadata != nil {
-		return *r.objectMetadata
-	}
-	return nil
-}

storage/storage.go

@@ -937,7 +937,7 @@ func signedURLV2(bucket, name string, opts *SignedURLOptions) (string, error) {
 	return u.String(), nil
 }
 
-// ReadHandle associated with the object. This would be periodically refreshed.
+// ReadHandle associated with the object. This is periodically refreshed.
 type ReadHandle []byte
 
 // ObjectHandle provides operations on an object in a Google Cloud Storage bucket.
@@ -965,7 +965,7 @@ type ObjectHandle struct {
 // This produces the exact same object and generation and does not check if
 // the generation is still the newest one.
 // Note that this will be a noop unless it's set on a gRPC client on buckets with
-// appendable write access.
+// bi-directional read API access.
 // Also note that you can get a ReadHandle only via calling reader.ReadHandle() on a
 // previous read of the same object.
 func (o *ObjectHandle) ReadHandle(r ReadHandle) *ObjectHandle {

storage/writer.go

@@ -107,7 +107,8 @@ type Writer struct {
 	// visible on the first Write() call, and can be appended to until they are
 	// finalized. The object is finalized on a call to Close().
 	//
-	// Append is only supported for gRPC.
+	// Append is only supported for gRPC. This feature is in preview and is not
+	// yet available for general use.
 	Append bool
 
 	// ProgressFunc can be used to monitor the progress of a large write