Added comments for clarity

Author: suni72

gcsfs/core.py

@@ -2074,6 +2074,10 @@ def _convert_fixed_key_metadata(metadata, *, from_google=False):
 
 
 async def upload_chunk(fs, location, data, offset, size, content_type):
+    """
+    Uploads a chunk of data. This function has a conditional path to support
+    experimental features for Zonal buckets to append data using gRPC.
+    """
     from google.cloud.storage._experimental.asyncio.async_appendable_object_writer import (
         AsyncAppendableObjectWriter,
     )
@@ -2114,6 +2118,11 @@ async def initiate_upload(
     mode="overwrite",
     kms_key_name=None,
 ):
+    """
+    Initiates a resumable upload. This function has a conditional path to support
+    experimental features for Zonal buckets to append data using gRPC, returning an
+    "AsyncAppendableObjectWriter" instance as location.
+    """
     from .extended_gcsfs import ExtendedGcsFileSystem
     from .extended_gcsfs import initiate_upload as ext_initiate_upload
 
@@ -2164,6 +2173,10 @@ async def simple_upload(
     mode="overwrite",
     kms_key_name=None,
 ):
+    """
+    Performs a simple, single-request upload. This function has a conditional path to support
+    experimental features for Zonal buckets to upload data using gRPC.
+    """
     from .extended_gcsfs import ExtendedGcsFileSystem
     from .extended_gcsfs import simple_upload as ext_simple_upload
 

gcsfs/extended_gcsfs.py

@@ -252,7 +252,7 @@ async def _cat_file(self, path, start=None, end=None, mrd=None, **kwargs):
 
 async def upload_chunk(fs, location, data, offset, size, content_type):
     raise NotImplementedError(
-        "upload_chunk is not implemented yet for ExtendedGcsFileSystem. Please use write() instead."
+        "upload_chunk is not implemented yet for Zonal experimental feature. Please use write() instead."
     )
 
 
@@ -267,7 +267,7 @@ async def initiate_upload(
     kms_key_name=None,
 ):
     raise NotImplementedError(
-        "initiate_upload is not implemented yet for ExtendedGcsFileSystem. Please use write() instead."
+        "initiate_upload is not implemented yet for Zonal experimental feature. Please use write() instead."
     )
 
 
@@ -284,5 +284,5 @@ async def simple_upload(
     kms_key_name=None,
 ):
     raise NotImplementedError(
-        "simple_upload is not implemented yet for ExtendedGcsFileSystem. Please use write() instead."
+        "simple_upload is not implemented yet for Zonal experimental feature. Please use write() instead."
     )

gcsfs/zonal_file.py

@@ -63,6 +63,9 @@ def _fetch_range(self, start, end):
     def write(self, data):
         """
         Writes data using AsyncAppendableObjectWriter.
+
+        For more details, see the documentation for AsyncAppendableObjectWriter:
+        https://github.com/googleapis/python-storage/blob/9e6fefdc24a12a9189f7119bc9119e84a061842f/google/cloud/storage/_experimental/asyncio/async_appendable_object_writer.py#L38
         """
         if self.closed:
             raise ValueError("I/O operation on closed file.")
@@ -103,7 +106,7 @@ def commit(self):
     def discard(self):
         """Discard is not applicable for Zonal Buckets. Log a warning instead."""
         logger.warning(
-            "Discard is unavailable for Zonal Buckets. \
+            "Discard is not applicable for Zonal Buckets. \
             Data is uploaded via streaming and cannot be cancelled."
         )