From 36650a07cf98ee4e734e07f2403fe5d20e300fc8 Mon Sep 17 00:00:00 2001 From: Thomas Van Lenten Date: Mon, 7 Mar 2016 12:07:03 -0500 Subject: HeaderDoc support in the library and generated sources - Convert most of the core library headers over to HeaderDoc format. - Switch the generated comments over to HeaderDoc. - Create GPBCodedOutputStream_PackagePrivate and move some things into there that should be more internal. --- objectivec/GPBMessage.h | 227 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 179 insertions(+), 48 deletions(-) (limited to 'objectivec/GPBMessage.h') diff --git a/objectivec/GPBMessage.h b/objectivec/GPBMessage.h index 332393ed..58c42d02 100644 --- a/objectivec/GPBMessage.h +++ b/objectivec/GPBMessage.h @@ -44,23 +44,27 @@ NS_ASSUME_NONNULL_BEGIN CF_EXTERN_C_BEGIN -// NSError domain used for errors. +/// NSError domain used for errors. extern NSString *const GPBMessageErrorDomain; +/// Error code for NSError with GPBMessageErrorDomain. typedef NS_ENUM(NSInteger, GPBMessageErrorCode) { + /// The data being parsed is bad and a message can not be created from it. GPBMessageErrorCodeMalformedData = -100, + /// A message can't be serialized because it is missing required fields. GPBMessageErrorCodeMissingRequiredField = -101, }; -// In DEBUG ONLY, an NSException is thrown when a parsed message doesn't -// contain required fields. This key allows you to retrieve the parsed message -// from the exception's |userInfo| dictionary. #ifdef DEBUG +/// In DEBUG ONLY, an NSException is thrown when a parsed message doesn't +/// contain required fields. This key allows you to retrieve the parsed message +/// from the exception's @c userInfo dictionary. extern NSString *const GPBExceptionMessageKey; #endif // DEBUG CF_EXTERN_C_END +/// Base class for all of the generated message classes. @interface GPBMessage : NSObject // NOTE: If you add a instance method/property to this class that may conflict @@ -68,108 +72,235 @@ CF_EXTERN_C_END // The main cases are methods that take no arguments, or setFoo:/hasFoo: type // methods. +/// The unknown fields for this message. +/// +/// Only messages from proto files declared with "proto2" syntax support unknown +/// fields. For "proto3" syntax, any unknown fields found while parsing are +/// dropped. @property(nonatomic, copy, nullable) GPBUnknownFieldSet *unknownFields; -// Are all required fields in the message and all embedded messages set. +/// Are all required fields set in the message and all embedded messages. @property(nonatomic, readonly, getter=isInitialized) BOOL initialized; -// Returns an autoreleased instance. +/// Returns an autoreleased instance. + (instancetype)message; -// Create a message based on a variety of inputs. If there is a data parse -// error, nil is returned and if not NULL, errorPtr is filled in. -// NOTE: In DEBUG ONLY, the message is also checked for all required field, -// if one is missing, the parse will fail (returning nil, filling in errorPtr). +/// Creates a new instance by parsing the data. This method should be sent to +/// the generated message class that the data should be interpreted as. If +/// there is an error the method returns nil and the error is returned in +/// errorPtr (when provided). +/// +/// @note In DEBUG builds, the parsed message is checked to be sure all required +/// fields were provided, and the parse will fail if some are missing. +/// +/// @param data The data to parse. +/// @param errorPtr An optional error pointer to fill in with a failure reason if +/// the data can not be parsed. +/// +/// @return A new instance of the class messaged. + (instancetype)parseFromData:(NSData *)data error:(NSError **)errorPtr; + +/// Creates a new instance by parsing the data. This method should be sent to +/// the generated message class that the data should be interpreted as. If +/// there is an error the method returns nil and the error is returned in +/// errorPtr (when provided). +/// +/// @note In DEBUG builds, the parsed message is checked to be sure all required +/// fields were provided, and the parse will fail if some are missing. +/// +/// @param data The data to parse. +/// @param extensionRegistry The extension registry to use to look up extensions. +/// @param errorPtr An optional error pointer to fill in with a failure +/// reason if the data can not be parsed. +/// +/// @return A new instance of the class messaged. + (instancetype)parseFromData:(NSData *)data extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry error:(NSError **)errorPtr; + +/// Creates a new instance by parsing the data from the given input stream. This +/// method should be sent to the generated message class that the data should +/// be interpreted as. If there is an error the method returns nil and the error +/// is returned in errorPtr (when provided). +/// +/// @note In DEBUG builds, the parsed message is checked to be sure all required +/// fields were provided, and the parse will fail if some are missing. +/// +/// @param input The stream to read data from. +/// @param extensionRegistry The extension registry to use to look up extensions. +/// @param errorPtr An optional error pointer to fill in with a failure +/// reason if the data can not be parsed. +/// +/// @return A new instance of the class messaged. + (instancetype)parseFromCodedInputStream:(GPBCodedInputStream *)input extensionRegistry: (nullable GPBExtensionRegistry *)extensionRegistry error:(NSError **)errorPtr; -// Create a message based on delimited input. If there is a data parse -// error, nil is returned and if not NULL, errorPtr is filled in. +/// Creates a new instance by parsing the data from the given input stream. This +/// method should be sent to the generated message class that the data should +/// be interpreted as. If there is an error the method returns nil and the error +/// is returned in errorPtr (when provided). +/// +/// @note Unlike the parseFrom... methods, this never checks to see if all of +/// the required fields are set. So this method can be used to reload +/// messages that may not be complete. +/// +/// @param input The stream to read data from. +/// @param extensionRegistry The extension registry to use to look up extensions. +/// @param errorPtr An optional error pointer to fill in with a failure +/// reason if the data can not be parsed. +/// +/// @return A new instance of the class messaged. + (instancetype)parseDelimitedFromCodedInputStream:(GPBCodedInputStream *)input extensionRegistry: (nullable GPBExtensionRegistry *)extensionRegistry error:(NSError **)errorPtr; -// If there is a data parse error, nil is returned and if not NULL, errorPtr is -// filled in. -// NOTE: In DEBUG ONLY, the message is also checked for all required field, -// if one is missing, the parse will fail (returning nil, filling in errorPtr). +/// Initializes an instance by parsing the data. This method should be sent to +/// the generated message class that the data should be interpreted as. If +/// there is an error the method returns nil and the error is returned in +/// errorPtr (when provided). +/// +/// @note In DEBUG builds, the parsed message is checked to be sure all required +/// fields were provided, and the parse will fail if some are missing. +/// +/// @param data The data to parse. +/// @param errorPtr An optional error pointer to fill in with a failure reason if +/// the data can not be parsed. - (instancetype)initWithData:(NSData *)data error:(NSError **)errorPtr; + +/// Initializes an instance by parsing the data. This method should be sent to +/// the generated message class that the data should be interpreted as. If +/// there is an error the method returns nil and the error is returned in +/// errorPtr (when provided). +/// +/// @note In DEBUG builds, the parsed message is checked to be sure all required +/// fields were provided, and the parse will fail if some are missing. +/// +/// @param data The data to parse. +/// @param extensionRegistry The extension registry to use to look up extensions. +/// @param errorPtr An optional error pointer to fill in with a failure +/// reason if the data can not be parsed. - (instancetype)initWithData:(NSData *)data extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry error:(NSError **)errorPtr; + +/// Initializes an instance by parsing the data from the given input stream. This +/// method should be sent to the generated message class that the data should +/// be interpreted as. If there is an error the method returns nil and the error +/// is returned in errorPtr (when provided). +/// +/// @note Unlike the parseFrom... methods, this never checks to see if all of +/// the required fields are set. So this method can be used to reload +/// messages that may not be complete. +/// +/// @param input The stream to read data from. +/// @param extensionRegistry The extension registry to use to look up extensions. +/// @param errorPtr An optional error pointer to fill in with a failure +/// reason if the data can not be parsed. - (instancetype)initWithCodedInputStream:(GPBCodedInputStream *)input extensionRegistry: (nullable GPBExtensionRegistry *)extensionRegistry error:(NSError **)errorPtr; -// Serializes the message and writes it to output. +/// Writes out the message to the given output stream. - (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output; +/// Writes out the message to the given output stream. - (void)writeToOutputStream:(NSOutputStream *)output; -// Serializes the message and writes it to output, but writes the size of the -// message as a variant before writing the message. +/// Writes out a varint for the message size followed by the the message to +/// the given output stream. - (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output; +/// Writes out a varint for the message size followed by the the message to +/// the given output stream. - (void)writeDelimitedToOutputStream:(NSOutputStream *)output; -// Serializes the message to an NSData. Note that this value is not cached, so -// if you are using it repeatedly, cache it yourself. If there is an error -// while generating the data, nil is returned. -// NOTE: In DEBUG ONLY, the message is also checked for all required field, -// if one is missing, nil will be returned. +/// Serializes the message to a @c NSData. +/// +/// If there is an error while generating the data, nil is returned. +/// +/// @note This value is not cached, so if you are using it repeatedly, cache +/// it yourself. +/// +/// @note In DEBUG ONLY, the message is also checked for all required field, +/// if one is missing, nil will be returned. - (nullable NSData *)data; -// Same as -[data], except a delimiter is added to the start of the data -// indicating the size of the message data that follows. +/// Serializes a varint with the message size followed by the message data, +/// returning that as a @c NSData. +/// +/// @note This value is not cached, so if you are using it repeatedly, cache +/// it yourself. - (NSData *)delimitedData; -// Returns the size of the object if it were serialized. -// This is not a cached value. If you are following a pattern like this: -// size_t size = [aMsg serializedSize]; -// NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; -// [foo writeSize:size]; -// [foo appendData:[aMsg data]]; -// you would be better doing: -// NSData *data = [aMsg data]; -// NSUInteger size = [aMsg length]; -// NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; -// [foo writeSize:size]; -// [foo appendData:data]; +/// Calculates the size of the object if it were serialized. +/// +/// This is not a cached value. If you are following a pattern like this: +/// @code +/// size_t size = [aMsg serializedSize]; +/// NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; +/// [foo writeSize:size]; +/// [foo appendData:[aMsg data]]; +/// @endcode +/// you would be better doing: +/// @code +/// NSData *data = [aMsg data]; +/// NSUInteger size = [aMsg length]; +/// NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; +/// [foo writeSize:size]; +/// [foo appendData:data]; +/// @endcode - (size_t)serializedSize; -// Return the descriptor for the message +/// Return the descriptor for the message class. + (GPBDescriptor *)descriptor; +/// Return the descriptor for the message. - (GPBDescriptor *)descriptor; -// Extensions use boxed values (NSNumbers) for PODs, NSMutableArrays for -// repeated. If the extension is a Message one will be auto created for you -// and returned similar to fields. +/// Test to see if the given extension is set on the message. - (BOOL)hasExtension:(GPBExtensionDescriptor *)extension; + +/// Fetches the given extension's value for this message. +/// +/// Extensions use boxed values (NSNumbers) for PODs and NSMutableArrays for +/// repeated fields. If the extension is a Message one will be auto created for you +/// and returned similar to fields. - (nullable id)getExtension:(GPBExtensionDescriptor *)extension; + +/// Sets the given extension's value for this message. This is only for single +/// field extensions (i.e. - not repeated fields). +/// +/// Extensions use boxed values (@c NSNumbers). - (void)setExtension:(GPBExtensionDescriptor *)extension value:(nullable id)value; + +/// Adds the given value to the extension for this message. This is only for +/// repeated field extensions. If the field is a repeated POD type the @c value +/// is a @c NSNumber. - (void)addExtension:(GPBExtensionDescriptor *)extension value:(id)value; + +/// Replaces the given value at an index for the extension on this message. This +/// is only for repeated field extensions. If the field is a repeated POD type +/// the @c value is a @c NSNumber. - (void)setExtension:(GPBExtensionDescriptor *)extension index:(NSUInteger)index value:(id)value; + +/// Clears the given extension for this message. - (void)clearExtension:(GPBExtensionDescriptor *)extension; -// Resets all fields to their default values. +/// Resets all of the fields of this message to their default values. - (void)clear; -// Parses a message of this type from the input and merges it with this -// message. -// NOTE: This will throw if there is an error parsing the data. +/// Parses a message of this type from the input and merges it with this +/// message. +/// +/// @note This will throw if there is an error parsing the data. - (void)mergeFromData:(NSData *)data extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry; -// Merges the fields from another message (of the same type) into this -// message. +/// Merges the fields from another message (of the same type) into this +/// message. - (void)mergeFrom:(GPBMessage *)other; @end -- cgit v1.2.3