From 5fd71ce6312e6d7620f1f443d4181629695733a4 Mon Sep 17 00:00:00 2001
From: Thomas Van Lenten <thomasvl@google.com>
Date: Mon, 19 Jun 2017 10:21:33 -0400
Subject: [PATCH] ObjC: Document the exceptions on some of the writing apis.

---
 objectivec/GPBCodedOutputStream.h | 9 +++++++++
 objectivec/GPBCodedOutputStream.m | 9 +++++++--
 objectivec/GPBMessage.h           | 9 +++++++++
 3 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/objectivec/GPBCodedOutputStream.h b/objectivec/GPBCodedOutputStream.h
index d6fff3dbb6..23c404b853 100644
--- a/objectivec/GPBCodedOutputStream.h
+++ b/objectivec/GPBCodedOutputStream.h
@@ -46,12 +46,21 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * @c GPBCodedOutputStream exception names.
+ **/
+extern NSString *const GPBCodedOutputStreamException_OutOfSpace;
+extern NSString *const GPBCodedOutputStreamException_WriteFailed;
+
 /**
  * Writes out protocol message fields.
  *
  * The common uses of protocol buffers shouldn't need to use this class.
  * GPBMessage's provide a -data method that will serialize the message for you.
  *
+ * @note Any -write* api can raise the GPBCodedOutputStreamException_*
+ *       exceptions.
+ *
  * @note Subclassing of GPBCodedOutputStream is NOT supported.
  **/
 @interface GPBCodedOutputStream : NSObject
diff --git a/objectivec/GPBCodedOutputStream.m b/objectivec/GPBCodedOutputStream.m
index 7c3ab44715..c299040f0b 100644
--- a/objectivec/GPBCodedOutputStream.m
+++ b/objectivec/GPBCodedOutputStream.m
@@ -36,6 +36,11 @@
 #import "GPBUnknownFieldSet_PackagePrivate.h"
 #import "GPBUtilities_PackagePrivate.h"
 
+// These values are the existing values so as not to break any code that might
+// have already been inspecting them when they weren't documented/exposed.
+NSString *const GPBCodedOutputStreamException_OutOfSpace = @"OutOfSpace";
+NSString *const GPBCodedOutputStreamException_WriteFailed = @"WriteFailed";
+
 // Structure for containing state of a GPBCodedInputStream. Brought out into
 // a struct so that we can inline several common functions instead of dealing
 // with overhead of ObjC dispatch.
@@ -59,13 +64,13 @@ static const int32_t LITTLE_ENDIAN_64_SIZE = sizeof(uint64_t);
 static void GPBRefreshBuffer(GPBOutputBufferState *state) {
   if (state->output == nil) {
     // We're writing to a single buffer.
-    [NSException raise:@"OutOfSpace" format:@""];
+    [NSException raise:GPBCodedOutputStreamException_OutOfSpace format:@""];
   }
   if (state->position != 0) {
     NSInteger written =
         [state->output write:state->bytes maxLength:state->position];
     if (written != (NSInteger)state->position) {
-      [NSException raise:@"WriteFailed" format:@""];
+      [NSException raise:GPBCodedOutputStreamException_WriteFailed format:@""];
     }
     state->position = 0;
   }
diff --git a/objectivec/GPBMessage.h b/objectivec/GPBMessage.h
index 2c325ba85b..276740d2f9 100644
--- a/objectivec/GPBMessage.h
+++ b/objectivec/GPBMessage.h
@@ -292,6 +292,9 @@ CF_EXTERN_C_END
  * Writes out the message to the given coded output stream.
  *
  * @param output The coded output stream into which to write the message.
+ *
+ * @note This can raise the GPBCodedOutputStreamException_* exceptions.
+ *
  **/
 - (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output;
 
@@ -299,6 +302,8 @@ CF_EXTERN_C_END
  * Writes out the message to the given output stream.
  *
  * @param output The output stream into which to write the message.
+ *
+ * @note This can raise the GPBCodedOutputStreamException_* exceptions.
  **/
 - (void)writeToOutputStream:(NSOutputStream *)output;
 
@@ -307,6 +312,8 @@ CF_EXTERN_C_END
  * the given output stream.
  *
  * @param output The coded output stream into which to write the message.
+ *
+ * @note This can raise the GPBCodedOutputStreamException_* exceptions.
  **/
 - (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output;
 
@@ -315,6 +322,8 @@ CF_EXTERN_C_END
  * the given output stream.
  *
  * @param output The output stream into which to write the message.
+ *
+ * @note This can raise the GPBCodedOutputStreamException_* exceptions.
  **/
 - (void)writeDelimitedToOutputStream:(NSOutputStream *)output;