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.

1 files changed, 179 insertions, 48 deletions

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<NSSecureCoding, NSCopying>
 
 // 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