doc(storage): clarify ObjectIterator error case (#2844)

If ObjectIterator.Next returns any error, subsequent calls
will continue to return the error. See
https://github.com/googleapis/google-api-go-client/blob/d63bd5fbc004a083dc85ef622366115e8088da62/iterator/iterator.go#L106

This was a source of customer confusion recently, so I
added some clarity to the docs, as well as a suggestion
for how to address errors in a long-running iteration.

storage/bucket.go

@@ -1130,8 +1130,9 @@ func toUniformBucketLevelAccess(b *raw.BucketIamConfiguration) UniformBucketLeve
 	}
 }
 
-// Objects returns an iterator over the objects in the bucket that match the Query q.
-// If q is nil, no filtering is done.
+// Objects returns an iterator over the objects in the bucket that match the
+// Query q. If q is nil, no filtering is done. Objects will be iterated over
+// lexicographically by name.
 //
 // Note: The returned iterator is not safe for concurrent operations without explicit synchronization.
 func (b *BucketHandle) Objects(ctx context.Context, q *Query) *ObjectIterator {
@@ -1170,6 +1171,13 @@ func (it *ObjectIterator) PageInfo() *iterator.PageInfo { return it.pageInfo }
 // there are no more results. Once Next returns iterator.Done, all subsequent
 // calls will return iterator.Done.
 //
+// In addition, if Next returns an error other than iterator.Done, all
+// subsequent calls will return the same error. To continue iteration, a new
+// `ObjectIterator` must be created. Since objects are ordered lexicographically
+// by name, `Query.StartOffset` can be used to create a new iterator which will
+// start at the desired place. See
+// https://pkg.go.dev/cloud.google.com/go/storage?tab=doc#hdr-Listing_objects.
+//
 // If Query.Delimiter is non-empty, some of the ObjectAttrs returned by Next will
 // have a non-empty Prefix field, and a zero value for all other fields. These
 // represent prefixes.

storage/doc.go

@@ -138,6 +138,17 @@ Listing objects in a bucket is done with the Bucket.Objects method:
         names = append(names, attrs.Name)
     }
 
+Objects are listed lexicographically by name. To filter objects
+lexicographically, Query.StartOffset and/or Query.EndOffset can be used:
+
+    query := &storage.Query{
+        Prefix: "",
+        StartOffset: "bar/",  // Only list objects lexicographically >= "bar/"
+        EndOffset: "foo/",    // Only list objects lexicographically < "foo/"
+    }
+
+    // ... as before
+
 If only a subset of object attributes is needed when listing, specifying this
 subset using Query.SetAttrSelection may speed up the listing process: