third_party/protobuf: Update to HEAD (83d681ee2c)

third_party/protobuf/objectivec/GPBMessage.h

Index: third_party/protobuf/objectivec/GPBMessage.h
diff --git a/third_party/protobuf/objectivec/GPBMessage.h b/third_party/protobuf/objectivec/GPBMessage.h
index 58c42d02ee1d63875a30d2698f188a5a5394269e..c07ec8888d7a15cd15223d94c5696e9aa413552a 100644
--- a/third_party/protobuf/objectivec/GPBMessage.h
+++ b/third_party/protobuf/objectivec/GPBMessage.h
@@ -44,265 +44,413 @@ 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.
+/** Error codes for NSErrors originated in GPBMessage. */
 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.
+  /** Uncategorized error. */
+  GPBMessageErrorCodeOther = -100,
+  /** Message couldn't be serialized because it is missing required fields. */
   GPBMessageErrorCodeMissingRequiredField = -101,
 };
 
-#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
+/**
+ * Key under which the GPBMessage error's reason is stored inside the userInfo
+ * dictionary.
+ **/
+extern NSString *const GPBErrorReasonKey;
 
 CF_EXTERN_C_END
 
-/// Base class for all of the generated message classes.
+/**
+ * Base class that each generated message subclasses from.
+ *
+ * @note While the class support NSSecureCoding, if the message has any
+ *       extensions, they will end up reloaded in @c unknownFields as there is
+ *       no way for the @c NSCoding plumbing to pass through a
+ *       @c GPBExtensionRegistry. To support extensions, instead of passing the
+ *       calls off to the Message, simple store the result of @c data, and then
+ *       when loading, fetch the data and use
+ *       @c +parseFromData:extensionRegistry:error: to provide an extension
+ *       registry.
+ **/
 @interface GPBMessage : NSObject<NSSecureCoding, NSCopying>
 
-// NOTE: If you add a instance method/property to this class that may conflict
-// with methods declared in protos, you need to update objective_helpers.cc.
-// 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.
+// If you add an instance method/property to this class that may conflict with
+// fields declared in protos, you need to update objective_helpers.cc. The main
+// cases are methods that take no arguments, or setFoo:/hasFoo: type methods.
+
+/**
+ * The set of 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 set in the message and all embedded messages.
+/**
+ * Whether the message, along with all submessages, have the required fields
+ * set. This is only applicable for files declared with "proto2" syntax, as
+ * there are no required fields for "proto3" syntax.
+ **/
 @property(nonatomic, readonly, getter=isInitialized) BOOL initialized;
 
-/// Returns an autoreleased instance.
+/**
+ * @return An autoreleased message with the default values set.
+ **/
 + (instancetype)message;
 
-/// 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;
-
-/// 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
+/**
+ * Creates a new instance by parsing the provided 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.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @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 generated class.
+ **/
++ (nullable 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.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @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 generated class.
+ **/
++ (nullable 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.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @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 generated class.
+ **/
++ (nullable instancetype)parseFromCodedInputStream:(GPBCodedInputStream *)input
                                  extensionRegistry:
                                      (nullable GPBExtensionRegistry *)extensionRegistry
                                              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 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;
-
-/// Writes out the message to the given output stream.
+/**
+ * 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.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @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 generated class.
+ **/
++ (nullable instancetype)parseDelimitedFromCodedInputStream:(GPBCodedInputStream *)input
+                                          extensionRegistry:
+                                              (nullable GPBExtensionRegistry *)extensionRegistry
+                                                      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.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @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 An initialized instance of the generated class.
+ **/
+- (nullable 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.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @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 An initialized instance of the generated class.
+ **/
+- (nullable 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.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @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 An initialized instance of the generated class.
+ **/
+- (nullable instancetype)initWithCodedInputStream:(GPBCodedInputStream *)input
+                                extensionRegistry:
+                                    (nullable GPBExtensionRegistry *)extensionRegistry
+                                            error:(NSError **)errorPtr;
+
+/**
+ * Parses the given data as this message's class, and merges those values into
+ * this message.
+ *
+ * @param data              The binary representation of the message to merge.
+ * @param extensionRegistry The extension registry to use to look up extensions.
+ *
+ * @exception GPBCodedInputStreamException Exception thrown when parsing was
+ *                                         unsuccessful.
+ **/
+- (void)mergeFromData:(NSData *)data
+    extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
+
+/**
+ * Merges the fields from another message (of the same type) into this
+ * message.
+ *
+ * @param other Message to merge into this message.
+ **/
+- (void)mergeFrom:(GPBMessage *)other;
+
+/**
+ * Writes out the message to the given coded output stream.
+ *
+ * @param output The coded output stream into which to write the message.
+ **/
 - (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output;
-/// 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.
+ **/
 - (void)writeToOutputStream:(NSOutputStream *)output;
 
-/// Writes out a varint for the message size followed by the the message to
-/// the given output stream.
+/**
+ * Writes out a varint for the message size followed by the the message to
+ * the given output stream.
+ *
+ * @param output The coded output stream into which to write the message.
+ **/
 - (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output;
-/// Writes out a varint for the message size followed by the the message to
-/// the given output stream.
+
+/**
+ * Writes out a varint for the message size followed by the the message to
+ * the given output stream.
+ *
+ * @param output The output stream into which to write the message.
+ **/
 - (void)writeDelimitedToOutputStream:(NSOutputStream *)output;
 
-/// 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.
+/**
+ * Serializes the message to an 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.
+ *
+ * @return The binary representation of the message.
+ **/
 - (nullable NSData *)data;
 
-/// 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.
+/**
+ * Serializes a varint with the message size followed by the message data,
+ * returning that as an NSData.
+ *
+ * @note This value is not cached, so if you are using it repeatedly, it is
+ *       recommended to keep a local copy.
+ *
+ * @return The binary representation of the size along with the message.
+ **/
 - (NSData *)delimitedData;
 
-/// 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
+/**
+ * Calculates 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];
+ * ```
+ *
+ * @return The size of the message in it's binary representation.
+ **/
 - (size_t)serializedSize;
 
-/// Return the descriptor for the message class.
+/**
+ * @return The descriptor for the message class.
+ **/
 + (GPBDescriptor *)descriptor;
-/// Return the descriptor for the message.
+
+/**
+ * Return the descriptor for the message.
+ **/
 - (GPBDescriptor *)descriptor;
 
-/// Test to see if the given extension is set on the message.
+/**
+ * @return An array with the extension descriptors that are currently set on the
+ * message.
+ **/
+- (NSArray *)extensionsCurrentlySet;
+
+/**
+ * Checks whether there is an extension set on the message which matches the
+ * given extension descriptor.
+ *
+ * @param extension Extension descriptor to check if it's set on the message.
+ *
+ * @return Whether the extension is currently 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.
+/*
+ * 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.
+ *
+ * @param extension The extension descriptor of the extension to fetch.
+ *
+ * @return The extension matching the given descriptor, or nil if none found.
+ **/
 - (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.
+/**
+ * Sets the given extension's value for this message. This only applies for
+ * single field extensions (i.e. - not repeated fields).
+ *
+ * Extensions use boxed values (NSNumbers).
+ *
+ * @param extension The extension descriptor under which to set the value.
+ * @param value     The value to be set as the extension.
+ **/
+- (void)setExtension:(GPBExtensionDescriptor *)extension
+               value:(nullable id)value;
+
+/**
+ * Adds the given value to the extension for this message. This only applies
+ * to repeated field extensions. If the field is a repeated POD type, the value
+ * should be an NSNumber.
+ *
+ * @param extension The extension descriptor under which to add the value.
+ * @param value     The value to be added to the repeated extension.
+ **/
 - (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.
+/**
+ * Replaces the value at the given index with the given value for the extension
+ * on this message. This only applies to repeated field extensions. If the field
+ * is a repeated POD type, the value is should be an NSNumber.
+ *
+ * @param extension The extension descriptor under which to replace the value.
+ * @param index     The index of the extension to be replaced.
+ * @param value     The value to be replaced in the repeated extension.
+ **/
 - (void)setExtension:(GPBExtensionDescriptor *)extension
                index:(NSUInteger)index
                value:(id)value;
 
-/// Clears the given extension for this message.
+/**
+ * Clears the given extension for this message.
+ *
+ * @param extension The extension descriptor to be cleared from this message.
+ **/
 - (void)clearExtension:(GPBExtensionDescriptor *)extension;
 
-/// Resets all of the fields of this message 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.
-- (void)mergeFromData:(NSData *)data
-    extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
-
-/// Merges the fields from another message (of the same type) into this
-/// message.
-- (void)mergeFrom:(GPBMessage *)other;
-
 @end
 
 NS_ASSUME_NONNULL_END