Merge pull request #3244 from thomasvl/complete_docs

ObjC: Document the exceptions on some of the writing apis.
This commit is contained in:
Thomas Van Lenten 2017-06-19 10:34:25 -04:00 committed by GitHub
commit 73b7cc0007
3 changed files with 25 additions and 2 deletions

View File

@ -46,12 +46,21 @@
NS_ASSUME_NONNULL_BEGIN NS_ASSUME_NONNULL_BEGIN
/**
* @c GPBCodedOutputStream exception names.
**/
extern NSString *const GPBCodedOutputStreamException_OutOfSpace;
extern NSString *const GPBCodedOutputStreamException_WriteFailed;
/** /**
* Writes out protocol message fields. * Writes out protocol message fields.
* *
* The common uses of protocol buffers shouldn't need to use this class. * 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. * 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. * @note Subclassing of GPBCodedOutputStream is NOT supported.
**/ **/
@interface GPBCodedOutputStream : NSObject @interface GPBCodedOutputStream : NSObject

View File

@ -36,6 +36,11 @@
#import "GPBUnknownFieldSet_PackagePrivate.h" #import "GPBUnknownFieldSet_PackagePrivate.h"
#import "GPBUtilities_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 // Structure for containing state of a GPBCodedInputStream. Brought out into
// a struct so that we can inline several common functions instead of dealing // a struct so that we can inline several common functions instead of dealing
// with overhead of ObjC dispatch. // 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) { static void GPBRefreshBuffer(GPBOutputBufferState *state) {
if (state->output == nil) { if (state->output == nil) {
// We're writing to a single buffer. // We're writing to a single buffer.
[NSException raise:@"OutOfSpace" format:@""]; [NSException raise:GPBCodedOutputStreamException_OutOfSpace format:@""];
} }
if (state->position != 0) { if (state->position != 0) {
NSInteger written = NSInteger written =
[state->output write:state->bytes maxLength:state->position]; [state->output write:state->bytes maxLength:state->position];
if (written != (NSInteger)state->position) { if (written != (NSInteger)state->position) {
[NSException raise:@"WriteFailed" format:@""]; [NSException raise:GPBCodedOutputStreamException_WriteFailed format:@""];
} }
state->position = 0; state->position = 0;
} }

View File

@ -292,6 +292,9 @@ CF_EXTERN_C_END
* Writes out the message to the given coded output stream. * Writes out the message to the given coded output stream.
* *
* @param output The coded output stream into which to write the message. * @param output The coded output stream into which to write the message.
*
* @note This can raise the GPBCodedOutputStreamException_* exceptions.
*
**/ **/
- (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output; - (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output;
@ -299,6 +302,8 @@ CF_EXTERN_C_END
* Writes out the message to the given output stream. * Writes out the message to the given output stream.
* *
* @param output The output stream into which to write the message. * @param output The output stream into which to write the message.
*
* @note This can raise the GPBCodedOutputStreamException_* exceptions.
**/ **/
- (void)writeToOutputStream:(NSOutputStream *)output; - (void)writeToOutputStream:(NSOutputStream *)output;
@ -307,6 +312,8 @@ CF_EXTERN_C_END
* the given output stream. * the given output stream.
* *
* @param output The coded output stream into which to write the message. * @param output The coded output stream into which to write the message.
*
* @note This can raise the GPBCodedOutputStreamException_* exceptions.
**/ **/
- (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output; - (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output;
@ -315,6 +322,8 @@ CF_EXTERN_C_END
* the given output stream. * the given output stream.
* *
* @param output The output stream into which to write the message. * @param output The output stream into which to write the message.
*
* @note This can raise the GPBCodedOutputStreamException_* exceptions.
**/ **/
- (void)writeDelimitedToOutputStream:(NSOutputStream *)output; - (void)writeDelimitedToOutputStream:(NSOutputStream *)output;