fix: Add documentation to Exceptions

README.md

@@ -49,20 +49,20 @@ If you are using Maven without BOM, add this to your dependencies:
 If you are using Gradle 5.x or later, add this to your dependencies:
 
 ```Groovy
-implementation platform('com.google.cloud:libraries-bom:26.0.0')
+implementation platform('com.google.cloud:libraries-bom:26.1.0')
 
 implementation 'com.google.cloud:google-cloud-bigquerystorage'
 ```
 If you are using Gradle without BOM, add this to your dependencies:
 
 ```Groovy
-implementation 'com.google.cloud:google-cloud-bigquerystorage:2.19.0'
+implementation 'com.google.cloud:google-cloud-bigquerystorage:2.19.1'
 ```
 
 If you are using SBT, add this to your dependencies:
 
 ```Scala
-libraryDependencies += "com.google.cloud" % "google-cloud-bigquerystorage" % "2.19.0"
+libraryDependencies += "com.google.cloud" % "google-cloud-bigquerystorage" % "2.19.1"
 ```
 
 ## Authentication

google-cloud-bigquerystorage/clirr-ignored-differences.xml

@@ -15,4 +15,13 @@
     <differenceType>8001</differenceType>
     <className>com/google/cloud/bigquery/storage/v1/Exceptions$WriterClosedException</className>
   </difference>
+  <difference>
+    <differenceType>5001</differenceType>
+    <className>com/google/cloud/bigquery/storage/v1/Exceptions$StreamWriterClosedException</className>
+  </difference>
+  <difference>
+    <differenceType>7004</differenceType>
+    <className>com/google/cloud/bigquery/storage/v1/Exceptions$StreamWriterClosedException</className>
+    <method>protected Exceptions$StreamWriterClosedException(io.grpc.Status, java.lang.String, java.lang.String)</method>
+  </difference>
 </differences>

google-cloud-bigquerystorage/src/main/java/com/google/cloud/bigquery/storage/v1/Exceptions.java

@@ -71,13 +71,22 @@ public long getActualOffset() {
     }
   }
 
-  /** Stream has already been finalized. */
+  /**
+   * The write stream has already been finalized and will not accept further appends or flushes. To
+   * send additional requests, you will need to create a new write stream via CreateWriteStream.
+   */
   public static final class StreamFinalizedException extends StorageException {
     protected StreamFinalizedException(Status grpcStatus, String name) {
       super(grpcStatus, name, null, null, ImmutableMap.of());
     }
   }
 
+  /**
+   * This writer instance has either been closed by the user explicitly, or has encountered
+   * non-retriable errors.
+   *
+   * <p>To continue to write to the same stream, you will need to create a new writer instance.
+   */
   public static final class StreamWriterClosedException extends StorageException {
     protected StreamWriterClosedException(Status grpcStatus, String name) {
       super(grpcStatus, name, null, null, ImmutableMap.of());
@@ -94,23 +103,36 @@ protected SchemaMismatchedException(Status grpcStatus, String name) {
     }
   }
 
-  /** Offset already exists. */
+  /**
+   * Offset already exists. This indicates that the append request attempted to write data to an
+   * offset before the current end of the stream. This is an expected exception when ExactOnce is
+   * enforced. You can safely ignore it, and keep appending until there is new data to append.
+   */
   public static final class OffsetAlreadyExists extends StorageException {
     protected OffsetAlreadyExists(
         Status grpcStatus, String name, Long expectedOffset, Long actualOffset) {
       super(grpcStatus, name, expectedOffset, actualOffset, ImmutableMap.of());
     }
   }
 
-  /** Offset out of range. */
+  /**
+   * Offset out of range. This indicates that the append request is attempting to write data to a
+   * point beyond the current end of the stream. To append data successfully, you must either
+   * specify the offset corresponding to the current end of stream, or omit the offset from the
+   * append request. It usually means a bug in your code that introduces a gap in appends.
+   */
   public static final class OffsetOutOfRange extends StorageException {
     protected OffsetOutOfRange(
         Status grpcStatus, String name, Long expectedOffset, Long actualOffset) {
       super(grpcStatus, name, expectedOffset, actualOffset, ImmutableMap.of());
     }
   }
 
-  /** Stream is not found. */
+  /**
+   * The stream is not found. Possible causes include incorrectly specifying the stream identifier
+   * or attempting to use an old stream identifier that no longer exists. You can invoke
+   * CreateWriteStream to create a new stream.
+   */
   public static final class StreamNotFound extends StorageException {
     protected StreamNotFound(Status grpcStatus, String name) {
       super(grpcStatus, name, null, null, ImmutableMap.of());