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, 104 insertions, 102 deletions

diff --git a/objectivec/GPBCodedOutputStream.h b/objectivec/GPBCodedOutputStream.h
index 0a47f1c9..e67efd2d 100644
--- a/objectivec/GPBCodedOutputStream.h
+++ b/objectivec/GPBCodedOutputStream.h
@@ -46,36 +46,63 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/// Writes out protocol message fields.
+///
+/// The common uses of protocol buffers shouldn't need to use this class.
+/// @c GPBMessage's provide a @c -data method that will serialize the message
+/// for you.
+///
+/// @note Subclassing of GPBCodedOutputStream is NOT supported.
 @interface GPBCodedOutputStream : NSObject
 
-// Creates a new stream to write into data.  Data must be sized to fit or it
-// will error when it runs out of space.
+/// Creates a stream to fill in the given data. Data must be sized to fit or
+/// an error will be raised when out of space.
 + (instancetype)streamWithData:(NSMutableData *)data;
+
+/// Creates a stream to write into the given @c NSOutputStream.
 + (instancetype)streamWithOutputStream:(NSOutputStream *)output;
-+ (instancetype)streamWithOutputStream:(NSOutputStream *)output
-                            bufferSize:(size_t)bufferSize;
 
+/// Initializes a stream to fill in the given data. Data must be sized to fit
+/// or an error will be raised when out of space.
 - (instancetype)initWithData:(NSMutableData *)data;
+
+/// Initializes a stream to write into the given @c NSOutputStream.
 - (instancetype)initWithOutputStream:(NSOutputStream *)output;
-- (instancetype)initWithOutputStream:(NSOutputStream *)output
-                          bufferSize:(size_t)bufferSize;
 
+/// Flush any buffered data out.
 - (void)flush;
 
+/// Write the raw byte out.
 - (void)writeRawByte:(uint8_t)value;
 
+/// Write the tag for the given field number and wire format.
+///
+/// @param fieldNumber The field number.
+/// @param format      The wire format the data for the field will be in.
 - (void)writeTag:(uint32_t)fieldNumber format:(GPBWireFormat)format;
 
+/// Write a 32bit value out in little endian format.
 - (void)writeRawLittleEndian32:(int32_t)value;
+/// Write a 64bit value out in little endian format.
 - (void)writeRawLittleEndian64:(int64_t)value;
 
+/// Write a 32bit value out in varint format.
 - (void)writeRawVarint32:(int32_t)value;
+/// Write a 64bit value out in varint format.
 - (void)writeRawVarint64:(int64_t)value;
 
-// Note that this will truncate 64 bit values to 32.
+/// Write a size_t out as a 32bit varint value.
+///
+/// @note This will truncate 64 bit values to 32.
 - (void)writeRawVarintSizeTAs32:(size_t)value;
 
+/// Writes the contents of an @c NSData out.
 - (void)writeRawData:(NSData *)data;
+/// Writes out the given data.
+///
+/// @param data   The data blob to write out.
+/// @param offset The offset into the blob to start writing out.
+/// @param length The number of bytes from the blob to write out.
 - (void)writeRawPtr:(const void *)data
              offset:(size_t)offset
              length:(size_t)length;
@@ -83,238 +110,213 @@ NS_ASSUME_NONNULL_BEGIN
 //%PDDM-EXPAND _WRITE_DECLS()
 // This block of code is generated, do not edit it directly.
 
+/// Write a double for the given field number.
 - (void)writeDouble:(int32_t)fieldNumber value:(double)value;
+/// Write a packaged array of double for the given field number.
 - (void)writeDoubleArray:(int32_t)fieldNumber
                   values:(GPBDoubleArray *)values
                      tag:(uint32_t)tag;
+/// Write a double without any tag.
 - (void)writeDoubleNoTag:(double)value;
 
+/// Write a float for the given field number.
 - (void)writeFloat:(int32_t)fieldNumber value:(float)value;
+/// Write a packaged array of float for the given field number.
 - (void)writeFloatArray:(int32_t)fieldNumber
                  values:(GPBFloatArray *)values
                     tag:(uint32_t)tag;
+/// Write a float without any tag.
 - (void)writeFloatNoTag:(float)value;
 
+/// Write a uint64_t for the given field number.
 - (void)writeUInt64:(int32_t)fieldNumber value:(uint64_t)value;
+/// Write a packaged array of uint64_t for the given field number.
 - (void)writeUInt64Array:(int32_t)fieldNumber
                   values:(GPBUInt64Array *)values
                      tag:(uint32_t)tag;
+/// Write a uint64_t without any tag.
 - (void)writeUInt64NoTag:(uint64_t)value;
 
+/// Write a int64_t for the given field number.
 - (void)writeInt64:(int32_t)fieldNumber value:(int64_t)value;
+/// Write a packaged array of int64_t for the given field number.
 - (void)writeInt64Array:(int32_t)fieldNumber
                  values:(GPBInt64Array *)values
                     tag:(uint32_t)tag;
+/// Write a int64_t without any tag.
 - (void)writeInt64NoTag:(int64_t)value;
 
+/// Write a int32_t for the given field number.
 - (void)writeInt32:(int32_t)fieldNumber value:(int32_t)value;
+/// Write a packaged array of int32_t for the given field number.
 - (void)writeInt32Array:(int32_t)fieldNumber
                  values:(GPBInt32Array *)values
                     tag:(uint32_t)tag;
+/// Write a int32_t without any tag.
 - (void)writeInt32NoTag:(int32_t)value;
 
+/// Write a uint32_t for the given field number.
 - (void)writeUInt32:(int32_t)fieldNumber value:(uint32_t)value;
+/// Write a packaged array of uint32_t for the given field number.
 - (void)writeUInt32Array:(int32_t)fieldNumber
                   values:(GPBUInt32Array *)values
                      tag:(uint32_t)tag;
+/// Write a uint32_t without any tag.
 - (void)writeUInt32NoTag:(uint32_t)value;
 
+/// Write a uint64_t for the given field number.
 - (void)writeFixed64:(int32_t)fieldNumber value:(uint64_t)value;
+/// Write a packaged array of uint64_t for the given field number.
 - (void)writeFixed64Array:(int32_t)fieldNumber
                    values:(GPBUInt64Array *)values
                       tag:(uint32_t)tag;
+/// Write a uint64_t without any tag.
 - (void)writeFixed64NoTag:(uint64_t)value;
 
+/// Write a uint32_t for the given field number.
 - (void)writeFixed32:(int32_t)fieldNumber value:(uint32_t)value;
+/// Write a packaged array of uint32_t for the given field number.
 - (void)writeFixed32Array:(int32_t)fieldNumber
                    values:(GPBUInt32Array *)values
                       tag:(uint32_t)tag;
+/// Write a uint32_t without any tag.
 - (void)writeFixed32NoTag:(uint32_t)value;
 
+/// Write a int32_t for the given field number.
 - (void)writeSInt32:(int32_t)fieldNumber value:(int32_t)value;
+/// Write a packaged array of int32_t for the given field number.
 - (void)writeSInt32Array:(int32_t)fieldNumber
                   values:(GPBInt32Array *)values
                      tag:(uint32_t)tag;
+/// Write a int32_t without any tag.
 - (void)writeSInt32NoTag:(int32_t)value;
 
+/// Write a int64_t for the given field number.
 - (void)writeSInt64:(int32_t)fieldNumber value:(int64_t)value;
+/// Write a packaged array of int64_t for the given field number.
 - (void)writeSInt64Array:(int32_t)fieldNumber
                   values:(GPBInt64Array *)values
                      tag:(uint32_t)tag;
+/// Write a int64_t without any tag.
 - (void)writeSInt64NoTag:(int64_t)value;
 
+/// Write a int64_t for the given field number.
 - (void)writeSFixed64:(int32_t)fieldNumber value:(int64_t)value;
+/// Write a packaged array of int64_t for the given field number.
 - (void)writeSFixed64Array:(int32_t)fieldNumber
                     values:(GPBInt64Array *)values
                        tag:(uint32_t)tag;
+/// Write a int64_t without any tag.
 - (void)writeSFixed64NoTag:(int64_t)value;
 
+/// Write a int32_t for the given field number.
 - (void)writeSFixed32:(int32_t)fieldNumber value:(int32_t)value;
+/// Write a packaged array of int32_t for the given field number.
 - (void)writeSFixed32Array:(int32_t)fieldNumber
                     values:(GPBInt32Array *)values
                        tag:(uint32_t)tag;
+/// Write a int32_t without any tag.
 - (void)writeSFixed32NoTag:(int32_t)value;
 
+/// Write a BOOL for the given field number.
 - (void)writeBool:(int32_t)fieldNumber value:(BOOL)value;
+/// Write a packaged array of BOOL for the given field number.
 - (void)writeBoolArray:(int32_t)fieldNumber
                 values:(GPBBoolArray *)values
                    tag:(uint32_t)tag;
+/// Write a BOOL without any tag.
 - (void)writeBoolNoTag:(BOOL)value;
 
+/// Write a int32_t for the given field number.
 - (void)writeEnum:(int32_t)fieldNumber value:(int32_t)value;
+/// Write a packaged array of int32_t for the given field number.
 - (void)writeEnumArray:(int32_t)fieldNumber
                 values:(GPBEnumArray *)values
                    tag:(uint32_t)tag;
+/// Write a int32_t without any tag.
 - (void)writeEnumNoTag:(int32_t)value;
 
+/// Write a NSString for the given field number.
 - (void)writeString:(int32_t)fieldNumber value:(NSString *)value;
+/// Write an array of NSString for the given field number.
 - (void)writeStringArray:(int32_t)fieldNumber values:(NSArray<NSString*> *)values;
+/// Write a NSString without any tag.
 - (void)writeStringNoTag:(NSString *)value;
 
+/// Write a GPBMessage for the given field number.
 - (void)writeMessage:(int32_t)fieldNumber value:(GPBMessage *)value;
+/// Write an array of GPBMessage for the given field number.
 - (void)writeMessageArray:(int32_t)fieldNumber values:(NSArray<GPBMessage*> *)values;
+/// Write a GPBMessage without any tag.
 - (void)writeMessageNoTag:(GPBMessage *)value;
 
+/// Write a NSData for the given field number.
 - (void)writeBytes:(int32_t)fieldNumber value:(NSData *)value;
+/// Write an array of NSData for the given field number.
 - (void)writeBytesArray:(int32_t)fieldNumber values:(NSArray<NSData*> *)values;
+/// Write a NSData without any tag.
 - (void)writeBytesNoTag:(NSData *)value;
 
+/// Write a GPBMessage for the given field number.
 - (void)writeGroup:(int32_t)fieldNumber
              value:(GPBMessage *)value;
+/// Write an array of GPBMessage for the given field number.
 - (void)writeGroupArray:(int32_t)fieldNumber values:(NSArray<GPBMessage*> *)values;
+/// Write a GPBMessage without any tag (but does write the endGroup tag).
 - (void)writeGroupNoTag:(int32_t)fieldNumber
                   value:(GPBMessage *)value;
 
+/// Write a GPBUnknownFieldSet for the given field number.
 - (void)writeUnknownGroup:(int32_t)fieldNumber
                     value:(GPBUnknownFieldSet *)value;
+/// Write an array of GPBUnknownFieldSet for the given field number.
 - (void)writeUnknownGroupArray:(int32_t)fieldNumber values:(NSArray<GPBUnknownFieldSet*> *)values;
+/// Write a GPBUnknownFieldSet without any tag (but does write the endGroup tag).
 - (void)writeUnknownGroupNoTag:(int32_t)fieldNumber
                          value:(GPBUnknownFieldSet *)value;
 
 //%PDDM-EXPAND-END _WRITE_DECLS()
 
-// Write a MessageSet extension field to the stream.  For historical reasons,
-// the wire format differs from normal fields.
+/// Write a MessageSet extension field to the stream. For historical reasons,
+/// the wire format differs from normal fields.
 - (void)writeMessageSetExtension:(int32_t)fieldNumber value:(GPBMessage *)value;
 
-// Write an unparsed MessageSet extension field to the stream.  For
-// historical reasons, the wire format differs from normal fields.
+/// Write an unparsed MessageSet extension field to the stream. For
+/// historical reasons, the wire format differs from normal fields.
 - (void)writeRawMessageSetExtension:(int32_t)fieldNumber value:(NSData *)value;
 
 @end
 
-CF_EXTERN_C_BEGIN
-
-size_t GPBComputeDoubleSize(int32_t fieldNumber, double value)
-    __attribute__((const));
-size_t GPBComputeFloatSize(int32_t fieldNumber, float value)
-    __attribute__((const));
-size_t GPBComputeUInt64Size(int32_t fieldNumber, uint64_t value)
-    __attribute__((const));
-size_t GPBComputeInt64Size(int32_t fieldNumber, int64_t value)
-    __attribute__((const));
-size_t GPBComputeInt32Size(int32_t fieldNumber, int32_t value)
-    __attribute__((const));
-size_t GPBComputeFixed64Size(int32_t fieldNumber, uint64_t value)
-    __attribute__((const));
-size_t GPBComputeFixed32Size(int32_t fieldNumber, uint32_t value)
-    __attribute__((const));
-size_t GPBComputeBoolSize(int32_t fieldNumber, BOOL value)
-    __attribute__((const));
-size_t GPBComputeStringSize(int32_t fieldNumber, NSString *value)
-    __attribute__((const));
-size_t GPBComputeGroupSize(int32_t fieldNumber, GPBMessage *value)
-    __attribute__((const));
-size_t GPBComputeUnknownGroupSize(int32_t fieldNumber,
-                                  GPBUnknownFieldSet *value)
-    __attribute__((const));
-size_t GPBComputeMessageSize(int32_t fieldNumber, GPBMessage *value)
-    __attribute__((const));
-size_t GPBComputeBytesSize(int32_t fieldNumber, NSData *value)
-    __attribute__((const));
-size_t GPBComputeUInt32Size(int32_t fieldNumber, uint32_t value)
-    __attribute__((const));
-size_t GPBComputeSFixed32Size(int32_t fieldNumber, int32_t value)
-    __attribute__((const));
-size_t GPBComputeSFixed64Size(int32_t fieldNumber, int64_t value)
-    __attribute__((const));
-size_t GPBComputeSInt32Size(int32_t fieldNumber, int32_t value)
-    __attribute__((const));
-size_t GPBComputeSInt64Size(int32_t fieldNumber, int64_t value)
-    __attribute__((const));
-size_t GPBComputeTagSize(int32_t fieldNumber) __attribute__((const));
-size_t GPBComputeWireFormatTagSize(int field_number, GPBDataType dataType)
-    __attribute__((const));
-
-size_t GPBComputeDoubleSizeNoTag(double value) __attribute__((const));
-size_t GPBComputeFloatSizeNoTag(float value) __attribute__((const));
-size_t GPBComputeUInt64SizeNoTag(uint64_t value) __attribute__((const));
-size_t GPBComputeInt64SizeNoTag(int64_t value) __attribute__((const));
-size_t GPBComputeInt32SizeNoTag(int32_t value) __attribute__((const));
-size_t GPBComputeFixed64SizeNoTag(uint64_t value) __attribute__((const));
-size_t GPBComputeFixed32SizeNoTag(uint32_t value) __attribute__((const));
-size_t GPBComputeBoolSizeNoTag(BOOL value) __attribute__((const));
-size_t GPBComputeStringSizeNoTag(NSString *value) __attribute__((const));
-size_t GPBComputeGroupSizeNoTag(GPBMessage *value) __attribute__((const));
-size_t GPBComputeUnknownGroupSizeNoTag(GPBUnknownFieldSet *value)
-    __attribute__((const));
-size_t GPBComputeMessageSizeNoTag(GPBMessage *value) __attribute__((const));
-size_t GPBComputeBytesSizeNoTag(NSData *value) __attribute__((const));
-size_t GPBComputeUInt32SizeNoTag(int32_t value) __attribute__((const));
-size_t GPBComputeEnumSizeNoTag(int32_t value) __attribute__((const));
-size_t GPBComputeSFixed32SizeNoTag(int32_t value) __attribute__((const));
-size_t GPBComputeSFixed64SizeNoTag(int64_t value) __attribute__((const));
-size_t GPBComputeSInt32SizeNoTag(int32_t value) __attribute__((const));
-size_t GPBComputeSInt64SizeNoTag(int64_t value) __attribute__((const));
-
-// Note that this will calculate the size of 64 bit values truncated to 32.
-size_t GPBComputeSizeTSizeAsInt32NoTag(size_t value) __attribute__((const));
-
-size_t GPBComputeRawVarint32Size(int32_t value) __attribute__((const));
-size_t GPBComputeRawVarint64Size(int64_t value) __attribute__((const));
-
-// Note that this will calculate the size of 64 bit values truncated to 32.
-size_t GPBComputeRawVarint32SizeForInteger(NSInteger value)
-    __attribute__((const));
-
-// Compute the number of bytes that would be needed to encode a
-// MessageSet extension to the stream.  For historical reasons,
-// the wire format differs from normal fields.
-size_t GPBComputeMessageSetExtensionSize(int32_t fieldNumber, GPBMessage *value)
-    __attribute__((const));
-
-// Compute the number of bytes that would be needed to encode an
-// unparsed MessageSet extension field to the stream.  For
-// historical reasons, the wire format differs from normal fields.
-size_t GPBComputeRawMessageSetExtensionSize(int32_t fieldNumber, NSData *value)
-    __attribute__((const));
-
-size_t GPBComputeEnumSize(int32_t fieldNumber, int32_t value)
-    __attribute__((const));
-
-CF_EXTERN_C_END
-
 NS_ASSUME_NONNULL_END
 
 // Write methods for types that can be in packed arrays.
 //%PDDM-DEFINE _WRITE_PACKABLE_DECLS(NAME, ARRAY_TYPE, TYPE)
+//%/// Write a TYPE for the given field number.
 //%- (void)write##NAME:(int32_t)fieldNumber value:(TYPE)value;
+//%/// Write a packaged array of TYPE for the given field number.
 //%- (void)write##NAME##Array:(int32_t)fieldNumber
 //%       NAME$S     values:(GPB##ARRAY_TYPE##Array *)values
 //%       NAME$S        tag:(uint32_t)tag;
+//%/// Write a TYPE without any tag.
 //%- (void)write##NAME##NoTag:(TYPE)value;
 //%
 // Write methods for types that aren't in packed arrays.
 //%PDDM-DEFINE _WRITE_UNPACKABLE_DECLS(NAME, TYPE)
+//%/// Write a TYPE for the given field number.
 //%- (void)write##NAME:(int32_t)fieldNumber value:(TYPE *)value;
+//%/// Write an array of TYPE for the given field number.
 //%- (void)write##NAME##Array:(int32_t)fieldNumber values:(NSArray<##TYPE##*> *)values;
+//%/// Write a TYPE without any tag.
 //%- (void)write##NAME##NoTag:(TYPE *)value;
 //%
 // Special write methods for Groups.
 //%PDDM-DEFINE _WRITE_GROUP_DECLS(NAME, TYPE)
+//%/// Write a TYPE for the given field number.
 //%- (void)write##NAME:(int32_t)fieldNumber
 //%       NAME$S value:(TYPE *)value;
+//%/// Write an array of TYPE for the given field number.
 //%- (void)write##NAME##Array:(int32_t)fieldNumber values:(NSArray<##TYPE##*> *)values;
+//%/// Write a TYPE without any tag (but does write the endGroup tag).
 //%- (void)write##NAME##NoTag:(int32_t)fieldNumber
 //%            NAME$S value:(TYPE *)value;
 //%