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/GPBCodedInputStream.h

@@ -35,52 +35,86 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-// Reads and decodes protocol message fields.
-// Subclassing of GPBCodedInputStream is NOT supported.
+/// Reads and decodes protocol message fields.
+///
+/// The common uses of protocol buffers shouldn't need to use this class.
+/// @c GPBMessage's provide a @c +parseFromData:error: and @c
+/// +parseFromData:extensionRegistry:error: method that will decode a
+/// message for you.
+///
+/// @note Subclassing of GPBCodedInputStream is NOT supported.
 @interface GPBCodedInputStream : NSObject
 
+/// Creates a new stream wrapping some data.
 + (instancetype)streamWithData:(NSData *)data;
+
+/// Initializes a stream wrapping some data.
 - (instancetype)initWithData:(NSData *)data;
 
-// Attempt to read a field tag, returning zero if we have reached EOF.
-// Protocol message parsers use this to read tags, since a protocol message
-// may legally end wherever a tag occurs, and zero is not a valid tag number.
+/// Attempt to read a field tag, returning zero if we have reached EOF.
+/// Protocol message parsers use this to read tags, since a protocol message
+/// may legally end wherever a tag occurs, and zero is not a valid tag number.
 - (int32_t)readTag;
 
+/// Read and return a double.
 - (double)readDouble;
+/// Read and return a float.
 - (float)readFloat;
+/// Read and return a uint64.
 - (uint64_t)readUInt64;
+/// Read and return a uint32.
 - (uint32_t)readUInt32;
+/// Read and return an int64.
 - (int64_t)readInt64;
+/// Read and return an int32.
 - (int32_t)readInt32;
+/// Read and return a fixed64.
 - (uint64_t)readFixed64;
+/// Read and return a fixed32.
 - (uint32_t)readFixed32;
+/// Read and return an enum (int).
 - (int32_t)readEnum;
+/// Read and return a sfixed32.
 - (int32_t)readSFixed32;
+/// Read and return a sfixed64.
 - (int64_t)readSFixed64;
+/// Read and return a sint32.
 - (int32_t)readSInt32;
+/// Read and return a sint64.
 - (int64_t)readSInt64;
+/// Read and return a boolean.
 - (BOOL)readBool;
+/// Read and return a string.
 - (NSString *)readString;
+/// Read and return length delimited data.
 - (NSData *)readBytes;
 
-// Read an embedded message field value from the stream.
+/// Read an embedded message field value from the stream.
+///
+/// @param message           The message to set fields on as they are read.
+/// @param extensionRegistry An optional extension registry to use to lookup
+///                          extensions for @message.
 - (void)readMessage:(GPBMessage *)message
-    extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
+  extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
 
-// Reads and discards a single field, given its tag value. Returns NO if the
-// tag is an endgroup tag, in which case nothing is skipped.  Otherwise,
-// returns YES.
+/// Reads and discards a single field, given its tag value.
+///
+/// @param tag The tag number of the field to skip.
+///
+/// @return NO if the tag is an endgroup tag (in which case nothing is skipped),
+///         YES in all other cases.
 - (BOOL)skipField:(int32_t)tag;
 
-// Reads and discards an entire message.  This will read either until EOF
-// or until an endgroup tag, whichever comes first.
+/// Reads and discards an entire message.  This will read either until EOF
+/// or until an endgroup tag, whichever comes first.
 - (void)skipMessage;
 
-// Verifies that the last call to readTag() returned the given tag value.
-// This is used to verify that a nested group ended with the correct end tag.
-// Throws NSParseErrorException if value does not match the last tag.
-- (void)checkLastTagWas:(int32_t)value;
+/// Verifies that the last call to @c -readTag returned the given tag value.
+/// This is used to verify that a nested group ended with the correct end tag.
+/// Throws @c NSParseErrorException if value does not match the last tag.
+///
+/// @param expected The tag that was expected.
+- (void)checkLastTagWas:(int32_t)expected;
 
 @end
 

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;
 //%

objectivec/GPBCodedOutputStream.m

@@ -28,7 +28,7 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-#import "GPBCodedOutputStream.h"
+#import "GPBCodedOutputStream_PackagePrivate.h"
 
 #import <mach/vm_param.h>
 
@@ -178,12 +178,6 @@ static void GPBWriteRawLittleEndian64(GPBOutputBufferState *state,
   return [self initWithOutputStream:nil data:data];
 }
 
-- (instancetype)initWithOutputStream:(NSOutputStream *)output
-                          bufferSize:(size_t)bufferSize {
-  NSMutableData *data = [NSMutableData dataWithLength:bufferSize];
-  return [self initWithOutputStream:output data:data];
-}
-
 // This initializer isn't exposed, but it is the designated initializer.
 // Setting OutputStream and NSData is to control the buffering behavior/size
 // of the work, but that is more obvious via the bufferSize: version.
@@ -199,15 +193,10 @@ static void GPBWriteRawLittleEndian64(GPBOutputBufferState *state,
   return self;
 }
 
-+ (instancetype)streamWithOutputStream:(NSOutputStream *)output
-                            bufferSize:(size_t)bufferSize {
-  return [[[self alloc] initWithOutputStream:output
-                                  bufferSize:bufferSize] autorelease];
-}
-
 + (instancetype)streamWithOutputStream:(NSOutputStream *)output {
+  NSMutableData *data = [NSMutableData dataWithLength:PAGE_SIZE];
   return [[[self alloc] initWithOutputStream:output
-                                  bufferSize:PAGE_SIZE] autorelease];
+                                        data:data] autorelease];
 }
 
 + (instancetype)streamWithData:(NSMutableData *)data {

objectivec/GPBCodedOutputStream_PackagePrivate.h

@@ -0,0 +1,126 @@
+// Protocol Buffers - Google's data interchange format
+// Copyright 2016 Google Inc.  All rights reserved.
+// https://developers.google.com/protocol-buffers/
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//     * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//     * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//     * Neither the name of Google Inc. nor the names of its
+// contributors may be used to endorse or promote products derived from
+// this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#import "GPBCodedOutputStream.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+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

objectivec/GPBDictionary.m

@@ -31,7 +31,7 @@
 #import "GPBDictionary_PackagePrivate.h"
 
 #import "GPBCodedInputStream_PackagePrivate.h"
-#import "GPBCodedOutputStream.h"
+#import "GPBCodedOutputStream_PackagePrivate.h"
 #import "GPBDescriptor_PackagePrivate.h"
 #import "GPBMessage_PackagePrivate.h"
 #import "GPBUtilities_PackagePrivate.h"

objectivec/GPBExtensionInternals.m

@@ -33,7 +33,7 @@
 #import <objc/runtime.h>
 
 #import "GPBCodedInputStream_PackagePrivate.h"
-#import "GPBCodedOutputStream.h"
+#import "GPBCodedOutputStream_PackagePrivate.h"
 #import "GPBDescriptor_PackagePrivate.h"
 #import "GPBMessage_PackagePrivate.h"
 #import "GPBUtilities_PackagePrivate.h"

objectivec/GPBExtensionRegistry.h

@@ -35,30 +35,45 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-// A table of known extensions, searchable by name or field number.  When
-// parsing a protocol message that might have extensions, you must provide an
-// ExtensionRegistry in which you have registered any extensions that you want
-// to be able to parse.  Otherwise, those extensions will just be treated like
-// unknown fields.
-//
-// The *Root classes provide +extensionRegistry for the extensions defined in a
-// given file *and* all files it imports.  You can also create a
-// GPBExtensionRegistry, and merge those registries to handle parsing extensions
-// defined from non overlapping files.
-//
-//    GPBExtensionRegistry *registry =
-//        [[[MyProtoFileRoot extensionRegistry] copy] autorelease];
-//    [registry addExtension:[OtherMessage neededExtension];  // Not in MyProtoFile
-//    NSError *parseError = nil;
-//    MyMessage *msg = [MyMessage parseData:data
-//                        extensionRegistry:registry
-//                                    error:&parseError];
-//
+/// A table of known extensions, searchable by name or field number.  When
+/// parsing a protocol message that might have extensions, you must provide a
+/// @c GPBExtensionRegistry in which you have registered any extensions that you
+/// want to be able to parse. Otherwise, those extensions will just be treated
+/// like unknown fields.
+///
+/// The @c *Root classes provide @c +extensionRegistry for the extensions defined
+/// in a given file *and* all files it imports. You can also create a
+/// @c GPBExtensionRegistry, and merge those registries to handle parsing
+/// extensions defined from non overlapping files.
+///
+/// @code
+/// GPBExtensionRegistry *registry =
+///     [[[MyProtoFileRoot extensionRegistry] copy] autorelease];
+/// [registry addExtension:[OtherMessage neededExtension];  // Not in MyProtoFile
+/// NSError *parseError = nil;
+/// MyMessage *msg = [MyMessage parseData:data
+///                     extensionRegistry:registry
+///                                 error:&parseError];
+/// @endcode
 @interface GPBExtensionRegistry : NSObject<NSCopying>
 
+/// Add the given @c GPBExtensionDescriptor to this registry.
+///
+/// @param extension The extension description to add.
 - (void)addExtension:(GPBExtensionDescriptor *)extension;
+
+/// Adds all the extensions from another registry to this registry.
+///
+/// @param registry The registry to merge into this registry.
 - (void)addExtensions:(GPBExtensionRegistry *)registry;
 
+/// Looks for the extension registered for the given field number on a given
+/// @c GPBDescriptor.
+///
+/// @param descriptor  The descriptor to look for a registered extension on.
+/// @param fieldNumber The field number of an extension to look for.
+///
+/// @return The registered @c GPBExtensionDescripto or nil if none was found.
 - (nullable GPBExtensionDescriptor *)extensionForDescriptor:(GPBDescriptor *)descriptor
                                                 fieldNumber:(NSInteger)fieldNumber;
 

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

objectivec/GPBMessage.m

@@ -35,7 +35,7 @@
 
 #import "GPBArray_PackagePrivate.h"
 #import "GPBCodedInputStream_PackagePrivate.h"
-#import "GPBCodedOutputStream.h"
+#import "GPBCodedOutputStream_PackagePrivate.h"
 #import "GPBDescriptor_PackagePrivate.h"
 #import "GPBDictionary_PackagePrivate.h"
 #import "GPBExtensionInternals.h"

objectivec/GPBRootObject.h

@@ -34,11 +34,12 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-// All Root Objects derive from GPBRootObject. It supplies a registry
-// for derived classes to register their extensions to.
+/// Every generated proto file defines a local "Root" class that exposes a
+/// @c GPBExtensionRegistry for all the extensions defined by that file and
+/// the files it depends on.
 @interface GPBRootObject : NSObject
 
-// Per class registry.
+/// An extension registry for the given file and all the files it depends on.
 + (GPBExtensionRegistry *)extensionRegistry;
 
 @end

objectivec/GPBUnknownField.h

@@ -37,22 +37,51 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/// Store an unknown field. These are used in conjunction with @c GPBUnknownFieldSet
 @interface GPBUnknownField : NSObject<NSCopying>
 
+/// The field number the data is stored under.
 @property(nonatomic, readonly, assign) int32_t number;
 
-// Only one of these will be set.
+/// An array of varint values for this field.
 @property(nonatomic, readonly, strong) GPBUInt64Array *varintList;
+
+/// An array of fixed32 values for this field.
 @property(nonatomic, readonly, strong) GPBUInt32Array *fixed32List;
+
+/// An array of fixed64 values for this field.
 @property(nonatomic, readonly, strong) GPBUInt64Array *fixed64List;
+
+/// An array of data values for this field.
 @property(nonatomic, readonly, strong) NSArray<NSData*> *lengthDelimitedList;
+
+/// An array of groups of values for this field.
 @property(nonatomic, readonly, strong) NSArray<GPBUnknownFieldSet*> *groupList;
 
-// Only one of these should be used per Field.
+
+/// Add a value to the varintList.
+///
+/// @param value The value to add.
 - (void)addVarint:(uint64_t)value;
+
+/// Add a value to the fixed32List.
+///
+/// @param value The value to add.
 - (void)addFixed32:(uint32_t)value;
+
+/// Add a value to the fixed64List.
+///
+/// @param value The value to add.
 - (void)addFixed64:(uint64_t)value;
+
+/// Add a value to the lengthDelimitedList.
+///
+/// @param value The value to add.
 - (void)addLengthDelimited:(NSData *)value;
+
+/// Add a value to the groupList.
+///
+/// @param value The value to add.
 - (void)addGroup:(GPBUnknownFieldSet *)value;
 
 @end

objectivec/GPBUnknownField.m

@@ -31,7 +31,7 @@
 #import "GPBUnknownField_PackagePrivate.h"
 
 #import "GPBArray.h"
-#import "GPBCodedOutputStream.h"
+#import "GPBCodedOutputStream_PackagePrivate.h"
 
 @implementation GPBUnknownField {
  @protected

objectivec/GPBUnknownFieldSet.h

@@ -34,15 +34,30 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/// A collection of unknown fields.
 @interface GPBUnknownFieldSet : NSObject<NSCopying>
 
+/// Tests to see if the given field number has a value.
+///
+/// @param number The field number to check.
+///
+/// @return YES if there is an unknown field for the given field number.
 - (BOOL)hasField:(int32_t)number;
+
+/// Fetches the @c GPBUnknownField for the given field number.
+///
+/// @param number The field number to look up.
+///
+/// @return The @c GPBUnknownField or nil.
 - (nullable GPBUnknownField *)getField:(int32_t)number;
+
+/// Returns the number of fields in this set.
 - (NSUInteger)countOfFields;
 
+/// Adds the given field to the set.
 - (void)addField:(GPBUnknownField *)field;
 
-// Returns an NSArray of the GPBUnknownFields sorted by the field numbers.
+/// Returns an NSArray of the @c GPBUnknownFields sorted by the field numbers.
 - (NSArray<GPBUnknownField*> *)sortedFields;
 
 @end

objectivec/GPBUtilities.h

@@ -38,24 +38,34 @@ CF_EXTERN_C_BEGIN
 
 NS_ASSUME_NONNULL_BEGIN
 
-// Generates a string that should be a valid "Text Format" for the C++ version
-// of Protocol Buffers. lineIndent can be nil if no additional line indent is
-// needed. The comments provide the names according to the ObjC library, they
-// most likely won't exactly match the original .proto file.
+/// Generates a string that should be a valid "Text Format" for the C++ version
+/// of Protocol Buffers.
+///
+///  @param message    The message to generate from.
+///  @param lineIndent A string to use as the prefix for all lines generated. Can
+///                    be nil if no extra indent is needed.
+///
+/// @return A @c NSString with the Text Format of the message.
 NSString *GPBTextFormatForMessage(GPBMessage *message,
                                   NSString * __nullable lineIndent);
+
+/// Generates a string that should be a valid "Text Format" for the C++ version
+/// of Protocol Buffers.
+///
+///  @param unknownSet The unknown field set to generate from.
+///  @param lineIndent A string to use as the prefix for all lines generated. Can
+///                    be nil if no extra indent is needed.
+///
+/// @return A @c NSString with the Text Format of the unknown field set.
 NSString *GPBTextFormatForUnknownFieldSet(GPBUnknownFieldSet * __nullable unknownSet,
                                           NSString * __nullable lineIndent);
 
-//
-// Test if the given field is set on a message.
-//
+/// Test if the given field is set on a message.
 BOOL GPBMessageHasFieldNumberSet(GPBMessage *self, uint32_t fieldNumber);
+/// Test if the given field is set on a message.
 BOOL GPBMessageHasFieldSet(GPBMessage *self, GPBFieldDescriptor *field);
 
-//
-// Clear the given field of a message.
-//
+/// Clear the given field of a message.
 void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field);
 
 //%PDDM-EXPAND GPB_ACCESSORS()
@@ -68,60 +78,100 @@ void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field);
 
 // Single Fields
 
+/// Gets the value of a bytes field.
 NSData *GPBGetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of a bytes field.
 void GPBSetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field, NSData *value);
 
+/// Gets the value of a string field.
 NSString *GPBGetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of a string field.
 void GPBSetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field, NSString *value);
 
+/// Gets the value of a message field.
 GPBMessage *GPBGetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of a message field.
 void GPBSetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value);
 
+/// Gets the value of a group field.
 GPBMessage *GPBGetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of a group field.
 void GPBSetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value);
 
+/// Gets the value of a bool field.
 BOOL GPBGetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of a bool field.
 void GPBSetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field, BOOL value);
 
+/// Gets the value of an int32 field.
 int32_t GPBGetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of an int32 field.
 void GPBSetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
 
+/// Gets the value of an uint32 field.
 uint32_t GPBGetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of an uint32 field.
 void GPBSetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field, uint32_t value);
 
+/// Gets the value of an int64 field.
 int64_t GPBGetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of an int64 field.
 void GPBSetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field, int64_t value);
 
+/// Gets the value of an uint64 field.
 uint64_t GPBGetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of an uint64 field.
 void GPBSetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field, uint64_t value);
 
+/// Gets the value of a float field.
 float GPBGetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of a float field.
 void GPBSetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field, float value);
 
+/// Gets the value of a double field.
 double GPBGetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of a double field.
 void GPBSetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field, double value);
 
-// Get/Set the given enum field of a message.  You can only Set values that are
-// members of the enum.  For proto3, when doing a Get, if the value isn't a
-// memeber of the enum, kGPBUnrecognizedEnumeratorValue will be returned. The
-// the functions with "Raw" in the will bypass all checks.
+/// Get the given enum field of a message. For proto3, if the value isn't a
+/// member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned.
+/// GPBGetMessageRawEnumField will bypass the check and return whatever value
+/// was set.
 int32_t GPBGetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Set the given enum field of a message. You can only set values that are
+/// members of the enum.
 void GPBSetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
+/// Get the given enum field of a message. No check is done to ensure the value
+/// was defined in the enum.
 int32_t GPBGetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Set the given enum field of a message. You can set the value to anything,
+/// even a value that is not a member of the enum.
 void GPBSetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
 
 // Repeated Fields
 
-// The object will/should be GPB*Array or NSMutableArray based on the field's
-// type.
+/// Gets the value of a repeated field.
+///
+/// The result will be @c GPB*Array or @c NSMutableArray based on the
+/// field's type.
 id GPBGetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of a repeated field.
+///
+/// The value should be @c GPB*Array or @c NSMutableArray based on the
+/// field's type.
 void GPBSetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field, id array);
 
 // Map Fields
 
-// The object will/should be GPB*Dictionary or NSMutableDictionary based on the
-// field's type.
+/// Gets the value of a map<> field.
+///
+/// The result will be @c GPB*Dictionary or @c NSMutableDictionary based on
+/// the field's type.
 id GPBGetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field);
+/// Sets the value of a map<> field.
+///
+/// The object should be @c GPB*Dictionary or @c NSMutableDictionary based
+/// on the field's type.
 void GPBSetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field, id dictionary);
 
 //%PDDM-EXPAND-END GPB_ACCESSORS()
@@ -144,44 +194,64 @@ CF_EXTERN_C_END
 //%
 //%// Single Fields
 //%
-//%GPB_ACCESSOR_SINGLE_FULL(Bytes, NSData, *)
-//%GPB_ACCESSOR_SINGLE_FULL(String, NSString, *)
-//%GPB_ACCESSOR_SINGLE_FULL(Message, GPBMessage, *)
-//%GPB_ACCESSOR_SINGLE_FULL(Group, GPBMessage, *)
-//%GPB_ACCESSOR_SINGLE(Bool, BOOL)
-//%GPB_ACCESSOR_SINGLE(Int32, int32_t)
-//%GPB_ACCESSOR_SINGLE(UInt32, uint32_t)
-//%GPB_ACCESSOR_SINGLE(Int64, int64_t)
-//%GPB_ACCESSOR_SINGLE(UInt64, uint64_t)
-//%GPB_ACCESSOR_SINGLE(Float, float)
-//%GPB_ACCESSOR_SINGLE(Double, double)
-//%// Get/Set the given enum field of a message.  You can only Set values that are
-//%// members of the enum.  For proto3, when doing a Get, if the value isn't a
-//%// memeber of the enum, kGPBUnrecognizedEnumeratorValue will be returned. The
-//%// the functions with "Raw" in the will bypass all checks.
+//%GPB_ACCESSOR_SINGLE_FULL(Bytes, NSData, , *)
+//%GPB_ACCESSOR_SINGLE_FULL(String, NSString, , *)
+//%GPB_ACCESSOR_SINGLE_FULL(Message, GPBMessage, , *)
+//%GPB_ACCESSOR_SINGLE_FULL(Group, GPBMessage, , *)
+//%GPB_ACCESSOR_SINGLE(Bool, BOOL, )
+//%GPB_ACCESSOR_SINGLE(Int32, int32_t, n)
+//%GPB_ACCESSOR_SINGLE(UInt32, uint32_t, n)
+//%GPB_ACCESSOR_SINGLE(Int64, int64_t, n)
+//%GPB_ACCESSOR_SINGLE(UInt64, uint64_t, n)
+//%GPB_ACCESSOR_SINGLE(Float, float, )
+//%GPB_ACCESSOR_SINGLE(Double, double, )
+//%/// Get the given enum field of a message. For proto3, if the value isn't a
+//%/// member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned.
+//%/// GPBGetMessageRawEnumField will bypass the check and return whatever value
+//%/// was set.
 //%int32_t GPBGetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field);
+//%/// Set the given enum field of a message. You can only set values that are
+//%/// members of the enum.
 //%void GPBSetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
+//%/// Get the given enum field of a message. No check is done to ensure the value
+//%/// was defined in the enum.
 //%int32_t GPBGetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field);
+//%/// Set the given enum field of a message. You can set the value to anything,
+//%/// even a value that is not a member of the enum.
 //%void GPBSetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
 //%
 //%// Repeated Fields
 //%
-//%// The object will/should be GPB*Array or NSMutableArray based on the field's
-//%// type.
+//%/// Gets the value of a repeated field.
+//%///
+//%/// The result will be @c GPB*Array or @c NSMutableArray based on the
+//%/// field's type.
 //%id GPBGetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field);
+//%/// Sets the value of a repeated field.
+//%///
+//%/// The value should be @c GPB*Array or @c NSMutableArray based on the
+//%/// field's type.
 //%void GPBSetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field, id array);
 //%
 //%// Map Fields
 //%
-//%// The object will/should be GPB*Dictionary or NSMutableDictionary based on the
-//%// field's type.
+//%/// Gets the value of a map<> field.
+//%///
+//%/// The result will be @c GPB*Dictionary or @c NSMutableDictionary based on
+//%/// the field's type.
 //%id GPBGetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field);
+//%/// Sets the value of a map<> field.
+//%///
+//%/// The object should be @c GPB*Dictionary or @c NSMutableDictionary based
+//%/// on the field's type.
 //%void GPBSetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field, id dictionary);
 //%
 
-//%PDDM-DEFINE GPB_ACCESSOR_SINGLE(NAME, TYPE)
-//%GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, )
-//%PDDM-DEFINE GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, TisP)
+//%PDDM-DEFINE GPB_ACCESSOR_SINGLE(NAME, TYPE, AN)
+//%GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, AN, )
+//%PDDM-DEFINE GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, AN, TisP)
+//%/// Gets the value of a##AN NAME$L field.
 //%TYPE TisP##GPBGetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field);
+//%/// Sets the value of a##AN NAME$L field.
 //%void GPBSetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field, TYPE TisP##value);
 //%

objectivec/ProtocolBuffers_OSX.xcodeproj/project.pbxproj

@@ -188,6 +188,7 @@
 		F4487C7C1AAE06AC00531423 /* GPBUtilities_PackagePrivate.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = GPBUtilities_PackagePrivate.h; sourceTree = "<group>"; };
 		F4487C7E1AAF62CD00531423 /* GPBMessageTests+Serialization.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "GPBMessageTests+Serialization.m"; sourceTree = "<group>"; };
 		F4487C821AAF6AB300531423 /* GPBMessageTests+Merge.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "GPBMessageTests+Merge.m"; sourceTree = "<group>"; };
+		F44929001C866B1900C2548A /* GPBCodedOutputStream_PackagePrivate.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = GPBCodedOutputStream_PackagePrivate.h; sourceTree = "<group>"; };
 		F451D3F51A8AAE8700B8A22C /* GPBProtocolBuffers_RuntimeSupport.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = GPBProtocolBuffers_RuntimeSupport.h; sourceTree = "<group>"; };
 		F45C69CB16DFD08D0081955B /* GPBExtensionInternals.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = GPBExtensionInternals.m; sourceTree = "<group>"; };
 		F45E57C61AE6DC6A000B7D99 /* text_format_map_unittest_data.txt */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text; path = text_format_map_unittest_data.txt; sourceTree = "<group>"; };
@@ -368,9 +369,10 @@
 		7461B4860F94F96B00A0C422 /* IO */ = {
 			isa = PBXGroup;
 			children = (
-				7461B48E0F94F99000A0C422 /* GPBCodedInputStream.h */,
 				51457B5F18D0B7AF00CCC606 /* GPBCodedInputStream_PackagePrivate.h */,
+				7461B48E0F94F99000A0C422 /* GPBCodedInputStream.h */,
 				7461B48F0F94F99000A0C422 /* GPBCodedInputStream.m */,
+				F44929001C866B1900C2548A /* GPBCodedOutputStream_PackagePrivate.h */,
 				7461B4900F94F99000A0C422 /* GPBCodedOutputStream.h */,
 				7461B4910F94F99000A0C422 /* GPBCodedOutputStream.m */,
 				7461B4E70F94F99000A0C422 /* GPBWireFormat.h */,

objectivec/ProtocolBuffers_iOS.xcodeproj/project.pbxproj

@@ -209,6 +209,7 @@
 		F4487C7D1AAE06C500531423 /* GPBUtilities_PackagePrivate.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = GPBUtilities_PackagePrivate.h; sourceTree = "<group>"; };
 		F4487C801AAF62FC00531423 /* GPBMessageTests+Serialization.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "GPBMessageTests+Serialization.m"; sourceTree = "<group>"; };
 		F4487C841AAF6AC500531423 /* GPBMessageTests+Merge.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "GPBMessageTests+Merge.m"; sourceTree = "<group>"; };
+		F44929021C866B3B00C2548A /* GPBCodedOutputStream_PackagePrivate.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = GPBCodedOutputStream_PackagePrivate.h; sourceTree = "<group>"; };
 		F451D3F61A8AAEA600B8A22C /* GPBProtocolBuffers_RuntimeSupport.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = GPBProtocolBuffers_RuntimeSupport.h; sourceTree = "<group>"; };
 		F45C69CB16DFD08D0081955B /* GPBExtensionInternals.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = GPBExtensionInternals.m; sourceTree = "<group>"; };
 		F45E57C81AE6DC98000B7D99 /* text_format_map_unittest_data.txt */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text; path = text_format_map_unittest_data.txt; sourceTree = "<group>"; };
@@ -405,9 +406,10 @@
 		7461B4860F94F96B00A0C422 /* IO */ = {
 			isa = PBXGroup;
 			children = (
-				7461B48E0F94F99000A0C422 /* GPBCodedInputStream.h */,
 				51457B5F18D0B7AF00CCC606 /* GPBCodedInputStream_PackagePrivate.h */,
+				7461B48E0F94F99000A0C422 /* GPBCodedInputStream.h */,
 				7461B48F0F94F99000A0C422 /* GPBCodedInputStream.m */,
+				F44929021C866B3B00C2548A /* GPBCodedOutputStream_PackagePrivate.h */,
 				7461B4900F94F99000A0C422 /* GPBCodedOutputStream.h */,
 				7461B4910F94F99000A0C422 /* GPBCodedOutputStream.m */,
 				7461B4E70F94F99000A0C422 /* GPBWireFormat.h */,

objectivec/Tests/GPBCodedOuputStreamTests.m

@@ -30,11 +30,30 @@
 
 #import "GPBTestUtilities.h"
 
-#import "GPBCodedOutputStream.h"
+#import "GPBCodedOutputStream_PackagePrivate.h"
 #import "GPBCodedInputStream.h"
 #import "GPBUtilities_PackagePrivate.h"
 #import "google/protobuf/Unittest.pbobjc.h"
 
+@interface GPBCodedOutputStream (InternalMethods)
+// Declared in the .m file, expose for testing.
+- (instancetype)initWithOutputStream:(NSOutputStream *)output
+                                data:(NSMutableData *)data;
+@end
+
+@interface GPBCodedOutputStream (Helper)
++ (instancetype)streamWithOutputStream:(NSOutputStream *)output
+                            bufferSize:(size_t)bufferSize;
+@end
+
+@implementation GPBCodedOutputStream (Helper)
++ (instancetype)streamWithOutputStream:(NSOutputStream *)output
+                            bufferSize:(size_t)bufferSize {
+  NSMutableData *data = [NSMutableData dataWithLength:bufferSize];
+  return [[[self alloc] initWithOutputStream:output data:data] autorelease];
+}
+@end
+
 @interface CodedOutputStreamTests : GPBTestCase
 @end
 

objectivec/google/protobuf/Any.pbobjc.h

@@ -15,13 +15,15 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - GPBAnyRoot
 
+/// Exposes the extension registry for this file.
+///
+/// The base class provides:
+/// @code
+///   + (GPBExtensionRegistry *)extensionRegistry;
+/// @endcode
+/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
+/// this file and all files that it depends on.
 @interface GPBAnyRoot : GPBRootObject
-
-// The base class provides:
-//   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
-// this file and all files that it depends on.
-
 @end
 
 #pragma mark - GPBAny
@@ -31,61 +33,61 @@ typedef GPB_ENUM(GPBAny_FieldNumber) {
   GPBAny_FieldNumber_Value = 2,
 };
 
-// `Any` contains an arbitrary serialized message along with a URL
-// that describes the type of the serialized message.
-//
-//
-// JSON
-// ====
-// The JSON representation of an `Any` value uses the regular
-// representation of the deserialized, embedded message, with an
-// additional field `@type` which contains the type URL. Example:
-//
-//     package google.profile;
-//     message Person {
-//       string first_name = 1;
-//       string last_name = 2;
-//     }
-//
-//     {
-//       "@type": "type.googleapis.com/google.profile.Person",
-//       "firstName": <string>,
-//       "lastName": <string>
-//     }
-//
-// If the embedded message type is well-known and has a custom JSON
-// representation, that representation will be embedded adding a field
-// `value` which holds the custom JSON in addition to the `@type`
-// field. Example (for message [google.protobuf.Duration][]):
-//
-//     {
-//       "@type": "type.googleapis.com/google.protobuf.Duration",
-//       "value": "1.212s"
-//     }
+/// `Any` contains an arbitrary serialized message along with a URL
+/// that describes the type of the serialized message.
+///
+///
+/// JSON
+/// ====
+/// The JSON representation of an `Any` value uses the regular
+/// representation of the deserialized, embedded message, with an
+/// additional field `\@type` which contains the type URL. Example:
+///
+///     package google.profile;
+///     message Person {
+///       string first_name = 1;
+///       string last_name = 2;
+///     }
+///
+///     {
+///       "\@type": "type.googleapis.com/google.profile.Person",
+///       "firstName": <string>,
+///       "lastName": <string>
+///     }
+///
+/// If the embedded message type is well-known and has a custom JSON
+/// representation, that representation will be embedded adding a field
+/// `value` which holds the custom JSON in addition to the `\@type`
+/// field. Example (for message [google.protobuf.Duration][]):
+///
+///     {
+///       "\@type": "type.googleapis.com/google.protobuf.Duration",
+///       "value": "1.212s"
+///     }
 @interface GPBAny : GPBMessage
 
-// A URL/resource name whose content describes the type of the
-// serialized message.
-//
-// For URLs which use the schema `http`, `https`, or no schema, the
-// following restrictions and interpretations apply:
-//
-// * If no schema is provided, `https` is assumed.
-// * The last segment of the URL's path must represent the fully
-//   qualified name of the type (as in `path/google.protobuf.Duration`).
-// * An HTTP GET on the URL must yield a [google.protobuf.Type][]
-//   value in binary format, or produce an error.
-// * Applications are allowed to cache lookup results based on the
-//   URL, or have them precompiled into a binary to avoid any
-//   lookup. Therefore, binary compatibility needs to be preserved
-//   on changes to types. (Use versioned type names to manage
-//   breaking changes.)
-//
-// Schemas other than `http`, `https` (or the empty schema) might be
-// used with implementation specific semantics.
+/// A URL/resource name whose content describes the type of the
+/// serialized message.
+///
+/// For URLs which use the schema `http`, `https`, or no schema, the
+/// following restrictions and interpretations apply:
+///
+/// * If no schema is provided, `https` is assumed.
+/// * The last segment of the URL's path must represent the fully
+///   qualified name of the type (as in `path/google.protobuf.Duration`).
+/// * An HTTP GET on the URL must yield a [google.protobuf.Type][]
+///   value in binary format, or produce an error.
+/// * Applications are allowed to cache lookup results based on the
+///   URL, or have them precompiled into a binary to avoid any
+///   lookup. Therefore, binary compatibility needs to be preserved
+///   on changes to types. (Use versioned type names to manage
+///   breaking changes.)
+///
+/// Schemas other than `http`, `https` (or the empty schema) might be
+/// used with implementation specific semantics.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL;
 
-// Must be valid serialized data of the above specified type.
+/// Must be valid serialized data of the above specified type.
 @property(nonatomic, readwrite, copy, null_resettable) NSData *value;
 
 @end

objectivec/google/protobuf/Api.pbobjc.h

@@ -21,13 +21,15 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - GPBApiRoot
 
+/// Exposes the extension registry for this file.
+///
+/// The base class provides:
+/// @code
+///   + (GPBExtensionRegistry *)extensionRegistry;
+/// @endcode
+/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
+/// this file and all files that it depends on.
 @interface GPBApiRoot : GPBRootObject
-
-// The base class provides:
-//   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
-// this file and all files that it depends on.
-
 @end
 
 #pragma mark - GPBApi
@@ -42,58 +44,67 @@ typedef GPB_ENUM(GPBApi_FieldNumber) {
   GPBApi_FieldNumber_Syntax = 7,
 };
 
-// Api is a light-weight descriptor for a protocol buffer service.
+/// Api is a light-weight descriptor for a protocol buffer service.
 @interface GPBApi : GPBMessage
 
-// The fully qualified name of this api, including package name
-// followed by the api's simple name.
+/// The fully qualified name of this api, including package name
+/// followed by the api's simple name.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *name;
 
-// The methods of this api, in unspecified order.
+/// The methods of this api, in unspecified order.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBMethod*> *methodsArray;
+/// The number of items in @c methodsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger methodsArray_Count;
 
-// Any metadata attached to the API.
+/// Any metadata attached to the API.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray;
+/// The number of items in @c optionsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger optionsArray_Count;
 
-// A version string for this api. If specified, must have the form
-// `major-version.minor-version`, as in `1.10`. If the minor version
-// is omitted, it defaults to zero. If the entire version field is
-// empty, the major version is derived from the package name, as
-// outlined below. If the field is not empty, the version in the
-// package name will be verified to be consistent with what is
-// provided here.
-//
-// The versioning schema uses [semantic
-// versioning](http://semver.org) where the major version number
-// indicates a breaking change and the minor version an additive,
-// non-breaking change. Both version numbers are signals to users
-// what to expect from different versions, and should be carefully
-// chosen based on the product plan.
-//
-// The major version is also reflected in the package name of the
-// API, which must end in `v<major-version>`, as in
-// `google.feature.v1`. For major versions 0 and 1, the suffix can
-// be omitted. Zero major versions must only be used for
-// experimental, none-GA apis.
+/// A version string for this api. If specified, must have the form
+/// `major-version.minor-version`, as in `1.10`. If the minor version
+/// is omitted, it defaults to zero. If the entire version field is
+/// empty, the major version is derived from the package name, as
+/// outlined below. If the field is not empty, the version in the
+/// package name will be verified to be consistent with what is
+/// provided here.
+///
+/// The versioning schema uses [semantic
+/// versioning](http://semver.org) where the major version number
+/// indicates a breaking change and the minor version an additive,
+/// non-breaking change. Both version numbers are signals to users
+/// what to expect from different versions, and should be carefully
+/// chosen based on the product plan.
+///
+/// The major version is also reflected in the package name of the
+/// API, which must end in `v<major-version>`, as in
+/// `google.feature.v1`. For major versions 0 and 1, the suffix can
+/// be omitted. Zero major versions must only be used for
+/// experimental, none-GA apis.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *version;
 
-// Source context for the protocol buffer service represented by this
-// message.
-@property(nonatomic, readwrite) BOOL hasSourceContext;
+/// Source context for the protocol buffer service represented by this
+/// message.
 @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext;
+/// Test to see if @c sourceContext has been set.
+@property(nonatomic, readwrite) BOOL hasSourceContext;
 
-// Included APIs. See [Mixin][].
+/// Included APIs. See [Mixin][].
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBMixin*> *mixinsArray;
+/// The number of items in @c mixinsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger mixinsArray_Count;
 
-// The source syntax of the service.
+/// The source syntax of the service.
 @property(nonatomic, readwrite) enum GPBSyntax syntax;
 
 @end
 
+/// Fetches the raw value of a @c GPBApi's @c syntax property, even
+/// if the value was not defined by the enum at the time the code was generated.
 int32_t GPBApi_Syntax_RawValue(GPBApi *message);
+/// Sets the raw value of an @c GPBApi's @c syntax property, allowing
+/// it to be set to a value that was not defined by the enum at the time the code
+/// was generated.
 void SetGPBApi_Syntax_RawValue(GPBApi *message, int32_t value);
 
 #pragma mark - GPBMethod
@@ -108,34 +119,40 @@ typedef GPB_ENUM(GPBMethod_FieldNumber) {
   GPBMethod_FieldNumber_Syntax = 7,
 };
 
-// Method represents a method of an api.
+/// Method represents a method of an api.
 @interface GPBMethod : GPBMessage
 
-// The simple name of this method.
+/// The simple name of this method.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *name;
 
-// A URL of the input message type.
+/// A URL of the input message type.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *requestTypeURL;
 
-// If true, the request is streamed.
+/// If true, the request is streamed.
 @property(nonatomic, readwrite) BOOL requestStreaming;
 
-// The URL of the output message type.
+/// The URL of the output message type.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *responseTypeURL;
 
-// If true, the response is streamed.
+/// If true, the response is streamed.
 @property(nonatomic, readwrite) BOOL responseStreaming;
 
-// Any metadata attached to the method.
+/// Any metadata attached to the method.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray;
+/// The number of items in @c optionsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger optionsArray_Count;
 
-// The source syntax of this method.
+/// The source syntax of this method.
 @property(nonatomic, readwrite) enum GPBSyntax syntax;
 
 @end
 
+/// Fetches the raw value of a @c GPBMethod's @c syntax property, even
+/// if the value was not defined by the enum at the time the code was generated.
 int32_t GPBMethod_Syntax_RawValue(GPBMethod *message);
+/// Sets the raw value of an @c GPBMethod's @c syntax property, allowing
+/// it to be set to a value that was not defined by the enum at the time the code
+/// was generated.
 void SetGPBMethod_Syntax_RawValue(GPBMethod *message, int32_t value);
 
 #pragma mark - GPBMixin
@@ -145,90 +162,90 @@ typedef GPB_ENUM(GPBMixin_FieldNumber) {
   GPBMixin_FieldNumber_Root = 2,
 };
 
-// Declares an API to be included in this API. The including API must
-// redeclare all the methods from the included API, but documentation
-// and options are inherited as follows:
-//
-// - If after comment and whitespace stripping, the documentation
-//   string of the redeclared method is empty, it will be inherited
-//   from the original method.
-//
-// - Each annotation belonging to the service config (http,
-//   visibility) which is not set in the redeclared method will be
-//   inherited.
-//
-// - If an http annotation is inherited, the path pattern will be
-//   modified as follows. Any version prefix will be replaced by the
-//   version of the including API plus the [root][] path if specified.
-//
-// Example of a simple mixin:
-//
-//     package google.acl.v1;
-//     service AccessControl {
-//       // Get the underlying ACL object.
-//       rpc GetAcl(GetAclRequest) returns (Acl) {
-//         option (google.api.http).get = "/v1/{resource=**}:getAcl";
-//       }
-//     }
-//
-//     package google.storage.v2;
-//     service Storage {
-//       rpc GetAcl(GetAclRequest) returns (Acl);
-//
-//       // Get a data record.
-//       rpc GetData(GetDataRequest) returns (Data) {
-//         option (google.api.http).get = "/v2/{resource=**}";
-//       }
-//     }
-//
-// Example of a mixin configuration:
-//
-//     apis:
-//     - name: google.storage.v2.Storage
-//       mixins:
-//       - name: google.acl.v1.AccessControl
-//
-// The mixin construct implies that all methods in `AccessControl` are
-// also declared with same name and request/response types in
-// `Storage`. A documentation generator or annotation processor will
-// see the effective `Storage.GetAcl` method after inherting
-// documentation and annotations as follows:
-//
-//     service Storage {
-//       // Get the underlying ACL object.
-//       rpc GetAcl(GetAclRequest) returns (Acl) {
-//         option (google.api.http).get = "/v2/{resource=**}:getAcl";
-//       }
-//       ...
-//     }
-//
-// Note how the version in the path pattern changed from `v1` to `v2`.
-//
-// If the `root` field in the mixin is specified, it should be a
-// relative path under which inherited HTTP paths are placed. Example:
-//
-//     apis:
-//     - name: google.storage.v2.Storage
-//       mixins:
-//       - name: google.acl.v1.AccessControl
-//         root: acls
-//
-// This implies the following inherited HTTP annotation:
-//
-//     service Storage {
-//       // Get the underlying ACL object.
-//       rpc GetAcl(GetAclRequest) returns (Acl) {
-//         option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
-//       }
-//       ...
-//     }
+/// Declares an API to be included in this API. The including API must
+/// redeclare all the methods from the included API, but documentation
+/// and options are inherited as follows:
+///
+/// - If after comment and whitespace stripping, the documentation
+///   string of the redeclared method is empty, it will be inherited
+///   from the original method.
+///
+/// - Each annotation belonging to the service config (http,
+///   visibility) which is not set in the redeclared method will be
+///   inherited.
+///
+/// - If an http annotation is inherited, the path pattern will be
+///   modified as follows. Any version prefix will be replaced by the
+///   version of the including API plus the [root][] path if specified.
+///
+/// Example of a simple mixin:
+///
+///     package google.acl.v1;
+///     service AccessControl {
+///       // Get the underlying ACL object.
+///       rpc GetAcl(GetAclRequest) returns (Acl) {
+///         option (google.api.http).get = "/v1/{resource=**}:getAcl";
+///       }
+///     }
+///
+///     package google.storage.v2;
+///     service Storage {
+///       rpc GetAcl(GetAclRequest) returns (Acl);
+///
+///       // Get a data record.
+///       rpc GetData(GetDataRequest) returns (Data) {
+///         option (google.api.http).get = "/v2/{resource=**}";
+///       }
+///     }
+///
+/// Example of a mixin configuration:
+///
+///     apis:
+///     - name: google.storage.v2.Storage
+///       mixins:
+///       - name: google.acl.v1.AccessControl
+///
+/// The mixin construct implies that all methods in `AccessControl` are
+/// also declared with same name and request/response types in
+/// `Storage`. A documentation generator or annotation processor will
+/// see the effective `Storage.GetAcl` method after inherting
+/// documentation and annotations as follows:
+///
+///     service Storage {
+///       // Get the underlying ACL object.
+///       rpc GetAcl(GetAclRequest) returns (Acl) {
+///         option (google.api.http).get = "/v2/{resource=**}:getAcl";
+///       }
+///       ...
+///     }
+///
+/// Note how the version in the path pattern changed from `v1` to `v2`.
+///
+/// If the `root` field in the mixin is specified, it should be a
+/// relative path under which inherited HTTP paths are placed. Example:
+///
+///     apis:
+///     - name: google.storage.v2.Storage
+///       mixins:
+///       - name: google.acl.v1.AccessControl
+///         root: acls
+///
+/// This implies the following inherited HTTP annotation:
+///
+///     service Storage {
+///       // Get the underlying ACL object.
+///       rpc GetAcl(GetAclRequest) returns (Acl) {
+///         option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
+///       }
+///       ...
+///     }
 @interface GPBMixin : GPBMessage
 
-// The fully qualified name of the API which is included.
+/// The fully qualified name of the API which is included.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *name;
 
-// If non-empty specifies a path under which inherited HTTP paths
-// are rooted.
+/// If non-empty specifies a path under which inherited HTTP paths
+/// are rooted.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *root;
 
 @end

objectivec/google/protobuf/Duration.pbobjc.h

@@ -15,13 +15,15 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - GPBDurationRoot
 
+/// Exposes the extension registry for this file.
+///
+/// The base class provides:
+/// @code
+///   + (GPBExtensionRegistry *)extensionRegistry;
+/// @endcode
+/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
+/// this file and all files that it depends on.
 @interface GPBDurationRoot : GPBRootObject
-
-// The base class provides:
-//   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
-// this file and all files that it depends on.
-
 @end
 
 #pragma mark - GPBDuration
@@ -31,58 +33,58 @@ typedef GPB_ENUM(GPBDuration_FieldNumber) {
   GPBDuration_FieldNumber_Nanos = 2,
 };
 
-// A Duration represents a signed, fixed-length span of time represented
-// as a count of seconds and fractions of seconds at nanosecond
-// resolution. It is independent of any calendar and concepts like "day"
-// or "month". It is related to Timestamp in that the difference between
-// two Timestamp values is a Duration and it can be added or subtracted
-// from a Timestamp. Range is approximately +-10,000 years.
-//
-// Example 1: Compute Duration from two Timestamps in pseudo code.
-//
-//     Timestamp start = ...;
-//     Timestamp end = ...;
-//     Duration duration = ...;
-//
-//     duration.seconds = end.seconds - start.seconds;
-//     duration.nanos = end.nanos - start.nanos;
-//
-//     if (duration.seconds < 0 && duration.nanos > 0) {
-//       duration.seconds += 1;
-//       duration.nanos -= 1000000000;
-//     } else if (durations.seconds > 0 && duration.nanos < 0) {
-//       duration.seconds -= 1;
-//       duration.nanos += 1000000000;
-//     }
-//
-// Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.
-//
-//     Timestamp start = ...;
-//     Duration duration = ...;
-//     Timestamp end = ...;
-//
-//     end.seconds = start.seconds + duration.seconds;
-//     end.nanos = start.nanos + duration.nanos;
-//
-//     if (end.nanos < 0) {
-//       end.seconds -= 1;
-//       end.nanos += 1000000000;
-//     } else if (end.nanos >= 1000000000) {
-//       end.seconds += 1;
-//       end.nanos -= 1000000000;
-//     }
+/// A Duration represents a signed, fixed-length span of time represented
+/// as a count of seconds and fractions of seconds at nanosecond
+/// resolution. It is independent of any calendar and concepts like "day"
+/// or "month". It is related to Timestamp in that the difference between
+/// two Timestamp values is a Duration and it can be added or subtracted
+/// from a Timestamp. Range is approximately +-10,000 years.
+///
+/// Example 1: Compute Duration from two Timestamps in pseudo code.
+///
+///     Timestamp start = ...;
+///     Timestamp end = ...;
+///     Duration duration = ...;
+///
+///     duration.seconds = end.seconds - start.seconds;
+///     duration.nanos = end.nanos - start.nanos;
+///
+///     if (duration.seconds < 0 && duration.nanos > 0) {
+///       duration.seconds += 1;
+///       duration.nanos -= 1000000000;
+///     } else if (durations.seconds > 0 && duration.nanos < 0) {
+///       duration.seconds -= 1;
+///       duration.nanos += 1000000000;
+///     }
+///
+/// Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.
+///
+///     Timestamp start = ...;
+///     Duration duration = ...;
+///     Timestamp end = ...;
+///
+///     end.seconds = start.seconds + duration.seconds;
+///     end.nanos = start.nanos + duration.nanos;
+///
+///     if (end.nanos < 0) {
+///       end.seconds -= 1;
+///       end.nanos += 1000000000;
+///     } else if (end.nanos >= 1000000000) {
+///       end.seconds += 1;
+///       end.nanos -= 1000000000;
+///     }
 @interface GPBDuration : GPBMessage
 
-// Signed seconds of the span of time. Must be from -315,576,000,000
-// to +315,576,000,000 inclusive.
+/// Signed seconds of the span of time. Must be from -315,576,000,000
+/// to +315,576,000,000 inclusive.
 @property(nonatomic, readwrite) int64_t seconds;
 
-// Signed fractions of a second at nanosecond resolution of the span
-// of time. Durations less than one second are represented with a 0
-// `seconds` field and a positive or negative `nanos` field. For durations
-// of one second or more, a non-zero value for the `nanos` field must be
-// of the same sign as the `seconds` field. Must be from -999,999,999
-// to +999,999,999 inclusive.
+/// Signed fractions of a second at nanosecond resolution of the span
+/// of time. Durations less than one second are represented with a 0
+/// `seconds` field and a positive or negative `nanos` field. For durations
+/// of one second or more, a non-zero value for the `nanos` field must be
+/// of the same sign as the `seconds` field. Must be from -999,999,999
+/// to +999,999,999 inclusive.
 @property(nonatomic, readwrite) int32_t nanos;
 
 @end

objectivec/google/protobuf/Empty.pbobjc.h

@@ -15,26 +15,28 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - GPBEmptyRoot
 
+/// Exposes the extension registry for this file.
+///
+/// The base class provides:
+/// @code
+///   + (GPBExtensionRegistry *)extensionRegistry;
+/// @endcode
+/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
+/// this file and all files that it depends on.
 @interface GPBEmptyRoot : GPBRootObject
-
-// The base class provides:
-//   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
-// this file and all files that it depends on.
-
 @end
 
 #pragma mark - GPBEmpty
 
-// A generic empty message that you can re-use to avoid defining duplicated
-// empty messages in your APIs. A typical example is to use it as the request
-// or the response type of an API method. For instance:
-//
-//     service Foo {
-//       rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
-//     }
-//
-// The JSON representation for `Empty` is empty JSON object `{}`.
+/// A generic empty message that you can re-use to avoid defining duplicated
+/// empty messages in your APIs. A typical example is to use it as the request
+/// or the response type of an API method. For instance:
+///
+///     service Foo {
+///       rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
+///     }
+///
+/// The JSON representation for `Empty` is empty JSON object `{}`.
 @interface GPBEmpty : GPBMessage
 
 @end

objectivec/google/protobuf/FieldMask.pbobjc.h

@@ -15,13 +15,15 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - GPBFieldMaskRoot
 
+/// Exposes the extension registry for this file.
+///
+/// The base class provides:
+/// @code
+///   + (GPBExtensionRegistry *)extensionRegistry;
+/// @endcode
+/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
+/// this file and all files that it depends on.
 @interface GPBFieldMaskRoot : GPBRootObject
-
-// The base class provides:
-//   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
-// this file and all files that it depends on.
-
 @end
 
 #pragma mark - GPBFieldMask
@@ -30,132 +32,133 @@ typedef GPB_ENUM(GPBFieldMask_FieldNumber) {
   GPBFieldMask_FieldNumber_PathsArray = 1,
 };
 
-// `FieldMask` represents a set of symbolic field paths, for example:
-//
-//     paths: "f.a"
-//     paths: "f.b.d"
-//
-// Here `f` represents a field in some root message, `a` and `b`
-// fields in the message found in `f`, and `d` a field found in the
-// message in `f.b`.
-//
-// Field masks are used to specify a subset of fields that should be
-// returned by a get operation or modified by an update operation.
-// Field masks also have a custom JSON encoding (see below).
-//
-// # Field Masks in Projections
-//
-// When used in the context of a projection, a response message or
-// sub-message is filtered by the API to only contain those fields as
-// specified in the mask. For example, if the mask in the previous
-// example is applied to a response message as follows:
-//
-//     f {
-//       a : 22
-//       b {
-//         d : 1
-//         x : 2
-//       }
-//       y : 13
-//     }
-//     z: 8
-//
-// The result will not contain specific values for fields x,y and z
-// (their value will be set to the default, and omitted in proto text
-// output):
-//
-//
-//     f {
-//       a : 22
-//       b {
-//         d : 1
-//       }
-//     }
-//
-// A repeated field is not allowed except at the last position of a
-// field mask.
-//
-// If a FieldMask object is not present in a get operation, the
-// operation applies to all fields (as if a FieldMask of all fields
-// had been specified).
-//
-// Note that a field mask does not necessarily applies to the
-// top-level response message. In case of a REST get operation, the
-// field mask applies directly to the response, but in case of a REST
-// list operation, the mask instead applies to each individual message
-// in the returned resource list. In case of a REST custom method,
-// other definitions may be used. Where the mask applies will be
-// clearly documented together with its declaration in the API.  In
-// any case, the effect on the returned resource/resources is required
-// behavior for APIs.
-//
-// # Field Masks in Update Operations
-//
-// A field mask in update operations specifies which fields of the
-// targeted resource are going to be updated. The API is required
-// to only change the values of the fields as specified in the mask
-// and leave the others untouched. If a resource is passed in to
-// describe the updated values, the API ignores the values of all
-// fields not covered by the mask.
-//
-// In order to reset a field's value to the default, the field must
-// be in the mask and set to the default value in the provided resource.
-// Hence, in order to reset all fields of a resource, provide a default
-// instance of the resource and set all fields in the mask, or do
-// not provide a mask as described below.
-//
-// If a field mask is not present on update, the operation applies to
-// all fields (as if a field mask of all fields has been specified).
-// Note that in the presence of schema evolution, this may mean that
-// fields the client does not know and has therefore not filled into
-// the request will be reset to their default. If this is unwanted
-// behavior, a specific service may require a client to always specify
-// a field mask, producing an error if not.
-//
-// As with get operations, the location of the resource which
-// describes the updated values in the request message depends on the
-// operation kind. In any case, the effect of the field mask is
-// required to be honored by the API.
-//
-// ## Considerations for HTTP REST
-//
-// The HTTP kind of an update operation which uses a field mask must
-// be set to PATCH instead of PUT in order to satisfy HTTP semantics
-// (PUT must only be used for full updates).
-//
-// # JSON Encoding of Field Masks
-//
-// In JSON, a field mask is encoded as a single string where paths are
-// separated by a comma. Fields name in each path are converted
-// to/from lower-camel naming conventions.
-//
-// As an example, consider the following message declarations:
-//
-//     message Profile {
-//       User user = 1;
-//       Photo photo = 2;
-//     }
-//     message User {
-//       string display_name = 1;
-//       string address = 2;
-//     }
-//
-// In proto a field mask for `Profile` may look as such:
-//
-//     mask {
-//       paths: "user.display_name"
-//       paths: "photo"
-//     }
-//
-// In JSON, the same mask is represented as below:
-//
-//     {
-//       mask: "user.displayName,photo"
-//     }
+/// `FieldMask` represents a set of symbolic field paths, for example:
+///
+///     paths: "f.a"
+///     paths: "f.b.d"
+///
+/// Here `f` represents a field in some root message, `a` and `b`
+/// fields in the message found in `f`, and `d` a field found in the
+/// message in `f.b`.
+///
+/// Field masks are used to specify a subset of fields that should be
+/// returned by a get operation or modified by an update operation.
+/// Field masks also have a custom JSON encoding (see below).
+///
+/// # Field Masks in Projections
+///
+/// When used in the context of a projection, a response message or
+/// sub-message is filtered by the API to only contain those fields as
+/// specified in the mask. For example, if the mask in the previous
+/// example is applied to a response message as follows:
+///
+///     f {
+///       a : 22
+///       b {
+///         d : 1
+///         x : 2
+///       }
+///       y : 13
+///     }
+///     z: 8
+///
+/// The result will not contain specific values for fields x,y and z
+/// (their value will be set to the default, and omitted in proto text
+/// output):
+///
+///
+///     f {
+///       a : 22
+///       b {
+///         d : 1
+///       }
+///     }
+///
+/// A repeated field is not allowed except at the last position of a
+/// field mask.
+///
+/// If a FieldMask object is not present in a get operation, the
+/// operation applies to all fields (as if a FieldMask of all fields
+/// had been specified).
+///
+/// Note that a field mask does not necessarily applies to the
+/// top-level response message. In case of a REST get operation, the
+/// field mask applies directly to the response, but in case of a REST
+/// list operation, the mask instead applies to each individual message
+/// in the returned resource list. In case of a REST custom method,
+/// other definitions may be used. Where the mask applies will be
+/// clearly documented together with its declaration in the API.  In
+/// any case, the effect on the returned resource/resources is required
+/// behavior for APIs.
+///
+/// # Field Masks in Update Operations
+///
+/// A field mask in update operations specifies which fields of the
+/// targeted resource are going to be updated. The API is required
+/// to only change the values of the fields as specified in the mask
+/// and leave the others untouched. If a resource is passed in to
+/// describe the updated values, the API ignores the values of all
+/// fields not covered by the mask.
+///
+/// In order to reset a field's value to the default, the field must
+/// be in the mask and set to the default value in the provided resource.
+/// Hence, in order to reset all fields of a resource, provide a default
+/// instance of the resource and set all fields in the mask, or do
+/// not provide a mask as described below.
+///
+/// If a field mask is not present on update, the operation applies to
+/// all fields (as if a field mask of all fields has been specified).
+/// Note that in the presence of schema evolution, this may mean that
+/// fields the client does not know and has therefore not filled into
+/// the request will be reset to their default. If this is unwanted
+/// behavior, a specific service may require a client to always specify
+/// a field mask, producing an error if not.
+///
+/// As with get operations, the location of the resource which
+/// describes the updated values in the request message depends on the
+/// operation kind. In any case, the effect of the field mask is
+/// required to be honored by the API.
+///
+/// ## Considerations for HTTP REST
+///
+/// The HTTP kind of an update operation which uses a field mask must
+/// be set to PATCH instead of PUT in order to satisfy HTTP semantics
+/// (PUT must only be used for full updates).
+///
+/// # JSON Encoding of Field Masks
+///
+/// In JSON, a field mask is encoded as a single string where paths are
+/// separated by a comma. Fields name in each path are converted
+/// to/from lower-camel naming conventions.
+///
+/// As an example, consider the following message declarations:
+///
+///     message Profile {
+///       User user = 1;
+///       Photo photo = 2;
+///     }
+///     message User {
+///       string display_name = 1;
+///       string address = 2;
+///     }
+///
+/// In proto a field mask for `Profile` may look as such:
+///
+///     mask {
+///       paths: "user.display_name"
+///       paths: "photo"
+///     }
+///
+/// In JSON, the same mask is represented as below:
+///
+///     {
+///       mask: "user.displayName,photo"
+///     }
 @interface GPBFieldMask : GPBMessage
 
-// The set of field mask paths.
+/// The set of field mask paths.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<NSString*> *pathsArray;
+/// The number of items in @c pathsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger pathsArray_Count;
 
 @end

objectivec/google/protobuf/SourceContext.pbobjc.h

@@ -15,13 +15,15 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - GPBSourceContextRoot
 
+/// Exposes the extension registry for this file.
+///
+/// The base class provides:
+/// @code
+///   + (GPBExtensionRegistry *)extensionRegistry;
+/// @endcode
+/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
+/// this file and all files that it depends on.
 @interface GPBSourceContextRoot : GPBRootObject
-
-// The base class provides:
-//   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
-// this file and all files that it depends on.
-
 @end
 
 #pragma mark - GPBSourceContext
@@ -30,12 +32,12 @@ typedef GPB_ENUM(GPBSourceContext_FieldNumber) {
   GPBSourceContext_FieldNumber_FileName = 1,
 };
 
-// `SourceContext` represents information about the source of a
-// protobuf element, like the file in which it is defined.
+/// `SourceContext` represents information about the source of a
+/// protobuf element, like the file in which it is defined.
 @interface GPBSourceContext : GPBMessage
 
-// The path-qualified name of the .proto file that contained the associated
-// protobuf element.  For example: `"google/protobuf/source.proto"`.
+/// The path-qualified name of the .proto file that contained the associated
+/// protobuf element.  For example: `"google/protobuf/source.proto"`.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *fileName;
 
 @end

objectivec/google/protobuf/Struct.pbobjc.h

@@ -19,29 +19,36 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - Enum GPBNullValue
 
-// `NullValue` is a singleton enumeration to represent the null value for the
-// `Value` type union.
-//
-//  The JSON representation for `NullValue` is JSON `null`.
+/// `NullValue` is a singleton enumeration to represent the null value for the
+/// `Value` type union.
+///
+///  The JSON representation for `NullValue` is JSON `null`.
 typedef GPB_ENUM(GPBNullValue) {
+  /// Value used if any message's field encounters a value that is not defined
+  /// by this enum. The message will also have C functions to get/set the rawValue
+  /// of the field.
   GPBNullValue_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue,
-  // Null value.
+  /// Null value.
   GPBNullValue_NullValue = 0,
 };
 
 GPBEnumDescriptor *GPBNullValue_EnumDescriptor(void);
 
+/// Checks to see if the given value is defined by the enum or was not known at
+/// the time this source was generated.
 BOOL GPBNullValue_IsValidValue(int32_t value);
 
 #pragma mark - GPBStructRoot
 
+/// Exposes the extension registry for this file.
+///
+/// The base class provides:
+/// @code
+///   + (GPBExtensionRegistry *)extensionRegistry;
+/// @endcode
+/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
+/// this file and all files that it depends on.
 @interface GPBStructRoot : GPBRootObject
-
-// The base class provides:
-//   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
-// this file and all files that it depends on.
-
 @end
 
 #pragma mark - GPBStruct
@@ -50,18 +57,19 @@ typedef GPB_ENUM(GPBStruct_FieldNumber) {
   GPBStruct_FieldNumber_Fields = 1,
 };
 
-// `Struct` represents a structured data value, consisting of fields
-// which map to dynamically typed values. In some languages, `Struct`
-// might be supported by a native representation. For example, in
-// scripting languages like JS a struct is represented as an
-// object. The details of that representation are described together
-// with the proto support for the language.
-//
-// The JSON representation for `Struct` is JSON object.
+/// `Struct` represents a structured data value, consisting of fields
+/// which map to dynamically typed values. In some languages, `Struct`
+/// might be supported by a native representation. For example, in
+/// scripting languages like JS a struct is represented as an
+/// object. The details of that representation are described together
+/// with the proto support for the language.
+///
+/// The JSON representation for `Struct` is JSON object.
 @interface GPBStruct : GPBMessage
 
-// Map of dynamically typed values.
+/// Map of dynamically typed values.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableDictionary<NSString*, GPBValue*> *fields;
+/// The number of items in @c fields without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger fields_Count;
 
 @end
@@ -87,40 +95,46 @@ typedef GPB_ENUM(GPBValue_Kind_OneOfCase) {
   GPBValue_Kind_OneOfCase_ListValue = 6,
 };
 
-// `Value` represents a dynamically typed value which can be either
-// null, a number, a string, a boolean, a recursive struct value, or a
-// list of values. A producer of value is expected to set one of that
-// variants, absence of any variant indicates an error.
-//
-// The JSON representation for `Value` is JSON value.
+/// `Value` represents a dynamically typed value which can be either
+/// null, a number, a string, a boolean, a recursive struct value, or a
+/// list of values. A producer of value is expected to set one of that
+/// variants, absence of any variant indicates an error.
+///
+/// The JSON representation for `Value` is JSON value.
 @interface GPBValue : GPBMessage
 
-// The kind of value.
+/// The kind of value.
 @property(nonatomic, readonly) GPBValue_Kind_OneOfCase kindOneOfCase;
 
-// Represents a null value.
+/// Represents a null value.
 @property(nonatomic, readwrite) GPBNullValue nullValue;
 
-// Represents a double value.
+/// Represents a double value.
 @property(nonatomic, readwrite) double numberValue;
 
-// Represents a string value.
+/// Represents a string value.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *stringValue;
 
-// Represents a boolean value.
+/// Represents a boolean value.
 @property(nonatomic, readwrite) BOOL boolValue;
 
-// Represents a structured value.
+/// Represents a structured value.
 @property(nonatomic, readwrite, strong, null_resettable) GPBStruct *structValue;
 
-// Represents a repeated `Value`.
+/// Represents a repeated `Value`.
 @property(nonatomic, readwrite, strong, null_resettable) GPBListValue *listValue;
 
 @end
 
+/// Fetches the raw value of a @c GPBValue's @c nullValue property, even
+/// if the value was not defined by the enum at the time the code was generated.
 int32_t GPBValue_NullValue_RawValue(GPBValue *message);
+/// Sets the raw value of an @c GPBValue's @c nullValue property, allowing
+/// it to be set to a value that was not defined by the enum at the time the code
+/// was generated.
 void SetGPBValue_NullValue_RawValue(GPBValue *message, int32_t value);
 
+/// Clears whatever value was set for the oneof 'kind'.
 void GPBValue_ClearKindOneOfCase(GPBValue *message);
 
 #pragma mark - GPBListValue
@@ -129,13 +143,14 @@ typedef GPB_ENUM(GPBListValue_FieldNumber) {
   GPBListValue_FieldNumber_ValuesArray = 1,
 };
 
-// `ListValue` is a wrapper around a repeated field of values.
-//
-// The JSON representation for `ListValue` is JSON array.
+/// `ListValue` is a wrapper around a repeated field of values.
+///
+/// The JSON representation for `ListValue` is JSON array.
 @interface GPBListValue : GPBMessage
 
-// Repeated field of dynamically typed values.
+/// Repeated field of dynamically typed values.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBValue*> *valuesArray;
+/// The number of items in @c valuesArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger valuesArray_Count;
 
 @end

objectivec/google/protobuf/Timestamp.pbobjc.h

@@ -15,13 +15,15 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - GPBTimestampRoot
 
+/// Exposes the extension registry for this file.
+///
+/// The base class provides:
+/// @code
+///   + (GPBExtensionRegistry *)extensionRegistry;
+/// @endcode
+/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
+/// this file and all files that it depends on.
 @interface GPBTimestampRoot : GPBRootObject
-
-// The base class provides:
-//   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
-// this file and all files that it depends on.
-
 @end
 
 #pragma mark - GPBTimestamp
@@ -31,70 +33,70 @@ typedef GPB_ENUM(GPBTimestamp_FieldNumber) {
   GPBTimestamp_FieldNumber_Nanos = 2,
 };
 
-// A Timestamp represents a point in time independent of any time zone
-// or calendar, represented as seconds and fractions of seconds at
-// nanosecond resolution in UTC Epoch time. It is encoded using the
-// Proleptic Gregorian Calendar which extends the Gregorian calendar
-// backwards to year one. It is encoded assuming all minutes are 60
-// seconds long, i.e. leap seconds are "smeared" so that no leap second
-// table is needed for interpretation. Range is from
-// 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
-// By restricting to that range, we ensure that we can convert to
-// and from  RFC 3339 date strings.
-// See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
-//
-// Example 1: Compute Timestamp from POSIX `time()`.
-//
-//     Timestamp timestamp;
-//     timestamp.set_seconds(time(NULL));
-//     timestamp.set_nanos(0);
-//
-// Example 2: Compute Timestamp from POSIX `gettimeofday()`.
-//
-//     struct timeval tv;
-//     gettimeofday(&tv, NULL);
-//
-//     Timestamp timestamp;
-//     timestamp.set_seconds(tv.tv_sec);
-//     timestamp.set_nanos(tv.tv_usec * 1000);
-//
-// Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
-//
-//     FILETIME ft;
-//     GetSystemTimeAsFileTime(&ft);
-//     UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
-//
-//     // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
-//     // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
-//     Timestamp timestamp;
-//     timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
-//     timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
-//
-// Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
-//
-//     long millis = System.currentTimeMillis();
-//
-//     Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
-//         .setNanos((int) ((millis % 1000) * 1000000)).build();
-//
-//
-// Example 5: Compute Timestamp from current time in Python.
-//
-//     now = time.time()
-//     seconds = int(now)
-//     nanos = int((now - seconds) * 10**9)
-//     timestamp = Timestamp(seconds=seconds, nanos=nanos)
+/// A Timestamp represents a point in time independent of any time zone
+/// or calendar, represented as seconds and fractions of seconds at
+/// nanosecond resolution in UTC Epoch time. It is encoded using the
+/// Proleptic Gregorian Calendar which extends the Gregorian calendar
+/// backwards to year one. It is encoded assuming all minutes are 60
+/// seconds long, i.e. leap seconds are "smeared" so that no leap second
+/// table is needed for interpretation. Range is from
+/// 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
+/// By restricting to that range, we ensure that we can convert to
+/// and from  RFC 3339 date strings.
+/// See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
+///
+/// Example 1: Compute Timestamp from POSIX `time()`.
+///
+///     Timestamp timestamp;
+///     timestamp.set_seconds(time(NULL));
+///     timestamp.set_nanos(0);
+///
+/// Example 2: Compute Timestamp from POSIX `gettimeofday()`.
+///
+///     struct timeval tv;
+///     gettimeofday(&tv, NULL);
+///
+///     Timestamp timestamp;
+///     timestamp.set_seconds(tv.tv_sec);
+///     timestamp.set_nanos(tv.tv_usec * 1000);
+///
+/// Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
+///
+///     FILETIME ft;
+///     GetSystemTimeAsFileTime(&ft);
+///     UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
+///
+///     // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
+///     // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
+///     Timestamp timestamp;
+///     timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
+///     timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
+///
+/// Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
+///
+///     long millis = System.currentTimeMillis();
+///
+///     Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
+///         .setNanos((int) ((millis % 1000) * 1000000)).build();
+///
+///
+/// Example 5: Compute Timestamp from current time in Python.
+///
+///     now = time.time()
+///     seconds = int(now)
+///     nanos = int((now - seconds) * 10**9)
+///     timestamp = Timestamp(seconds=seconds, nanos=nanos)
 @interface GPBTimestamp : GPBMessage
 
-// Represents seconds of UTC time since Unix epoch
-// 1970-01-01T00:00:00Z. Must be from from 0001-01-01T00:00:00Z to
-// 9999-12-31T23:59:59Z inclusive.
+/// Represents seconds of UTC time since Unix epoch
+/// 1970-01-01T00:00:00Z. Must be from from 0001-01-01T00:00:00Z to
+/// 9999-12-31T23:59:59Z inclusive.
 @property(nonatomic, readwrite) int64_t seconds;
 
-// Non-negative fractions of a second at nanosecond resolution. Negative
-// second values with fractions must still have non-negative nanos values
-// that count forward in time. Must be from 0 to 999,999,999
-// inclusive.
+/// Non-negative fractions of a second at nanosecond resolution. Negative
+/// second values with fractions must still have non-negative nanos values
+/// that count forward in time. Must be from 0 to 999,999,999
+/// inclusive.
 @property(nonatomic, readwrite) int32_t nanos;
 
 @end

objectivec/google/protobuf/Type.pbobjc.h

@@ -21,118 +21,135 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - Enum GPBSyntax
 
-// The syntax in which a protocol buffer element is defined.
+/// The syntax in which a protocol buffer element is defined.
 typedef GPB_ENUM(GPBSyntax) {
+  /// Value used if any message's field encounters a value that is not defined
+  /// by this enum. The message will also have C functions to get/set the rawValue
+  /// of the field.
   GPBSyntax_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue,
-  // Syntax `proto2`.
+  /// Syntax `proto2`.
   GPBSyntax_SyntaxProto2 = 0,
 
-  // Syntax `proto3`.
+  /// Syntax `proto3`.
   GPBSyntax_SyntaxProto3 = 1,
 };
 
 GPBEnumDescriptor *GPBSyntax_EnumDescriptor(void);
 
+/// Checks to see if the given value is defined by the enum or was not known at
+/// the time this source was generated.
 BOOL GPBSyntax_IsValidValue(int32_t value);
 
 #pragma mark - Enum GPBField_Kind
 
-// Basic field types.
+/// Basic field types.
 typedef GPB_ENUM(GPBField_Kind) {
+  /// Value used if any message's field encounters a value that is not defined
+  /// by this enum. The message will also have C functions to get/set the rawValue
+  /// of the field.
   GPBField_Kind_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue,
-  // Field type unknown.
+  /// Field type unknown.
   GPBField_Kind_TypeUnknown = 0,
 
-  // Field type double.
+  /// Field type double.
   GPBField_Kind_TypeDouble = 1,
 
-  // Field type float.
+  /// Field type float.
   GPBField_Kind_TypeFloat = 2,
 
-  // Field type int64.
+  /// Field type int64.
   GPBField_Kind_TypeInt64 = 3,
 
-  // Field type uint64.
+  /// Field type uint64.
   GPBField_Kind_TypeUint64 = 4,
 
-  // Field type int32.
+  /// Field type int32.
   GPBField_Kind_TypeInt32 = 5,
 
-  // Field type fixed64.
+  /// Field type fixed64.
   GPBField_Kind_TypeFixed64 = 6,
 
-  // Field type fixed32.
+  /// Field type fixed32.
   GPBField_Kind_TypeFixed32 = 7,
 
-  // Field type bool.
+  /// Field type bool.
   GPBField_Kind_TypeBool = 8,
 
-  // Field type string.
+  /// Field type string.
   GPBField_Kind_TypeString = 9,
 
-  // Field type group. Proto2 syntax only, and deprecated.
+  /// Field type group. Proto2 syntax only, and deprecated.
   GPBField_Kind_TypeGroup = 10,
 
-  // Field type message.
+  /// Field type message.
   GPBField_Kind_TypeMessage = 11,
 
-  // Field type bytes.
+  /// Field type bytes.
   GPBField_Kind_TypeBytes = 12,
 
-  // Field type uint32.
+  /// Field type uint32.
   GPBField_Kind_TypeUint32 = 13,
 
-  // Field type enum.
+  /// Field type enum.
   GPBField_Kind_TypeEnum = 14,
 
-  // Field type sfixed32.
+  /// Field type sfixed32.
   GPBField_Kind_TypeSfixed32 = 15,
 
-  // Field type sfixed64.
+  /// Field type sfixed64.
   GPBField_Kind_TypeSfixed64 = 16,
 
-  // Field type sint32.
+  /// Field type sint32.
   GPBField_Kind_TypeSint32 = 17,
 
-  // Field type sint64.
+  /// Field type sint64.
   GPBField_Kind_TypeSint64 = 18,
 };
 
 GPBEnumDescriptor *GPBField_Kind_EnumDescriptor(void);
 
+/// Checks to see if the given value is defined by the enum or was not known at
+/// the time this source was generated.
 BOOL GPBField_Kind_IsValidValue(int32_t value);
 
 #pragma mark - Enum GPBField_Cardinality
 
-// Whether a field is optional, required, or repeated.
+/// Whether a field is optional, required, or repeated.
 typedef GPB_ENUM(GPBField_Cardinality) {
+  /// Value used if any message's field encounters a value that is not defined
+  /// by this enum. The message will also have C functions to get/set the rawValue
+  /// of the field.
   GPBField_Cardinality_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue,
-  // For fields with unknown cardinality.
+  /// For fields with unknown cardinality.
   GPBField_Cardinality_CardinalityUnknown = 0,
 
-  // For optional fields.
+  /// For optional fields.
   GPBField_Cardinality_CardinalityOptional = 1,
 
-  // For required fields. Proto2 syntax only.
+  /// For required fields. Proto2 syntax only.
   GPBField_Cardinality_CardinalityRequired = 2,
 
-  // For repeated fields.
+  /// For repeated fields.
   GPBField_Cardinality_CardinalityRepeated = 3,
 };
 
 GPBEnumDescriptor *GPBField_Cardinality_EnumDescriptor(void);
 
+/// Checks to see if the given value is defined by the enum or was not known at
+/// the time this source was generated.
 BOOL GPBField_Cardinality_IsValidValue(int32_t value);
 
 #pragma mark - GPBTypeRoot
 
+/// Exposes the extension registry for this file.
+///
+/// The base class provides:
+/// @code
+///   + (GPBExtensionRegistry *)extensionRegistry;
+/// @endcode
+/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
+/// this file and all files that it depends on.
 @interface GPBTypeRoot : GPBRootObject
-
-// The base class provides:
-//   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
-// this file and all files that it depends on.
-
 @end
 
 #pragma mark - GPBType
@@ -146,34 +163,43 @@ typedef GPB_ENUM(GPBType_FieldNumber) {
   GPBType_FieldNumber_Syntax = 6,
 };
 
-// A protocol buffer message type.
+/// A protocol buffer message type.
 @interface GPBType : GPBMessage
 
-// The fully qualified message name.
+/// The fully qualified message name.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *name;
 
-// The list of fields.
+/// The list of fields.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBField*> *fieldsArray;
+/// The number of items in @c fieldsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger fieldsArray_Count;
 
-// The list of types appearing in `oneof` definitions in this type.
+/// The list of types appearing in `oneof` definitions in this type.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<NSString*> *oneofsArray;
+/// The number of items in @c oneofsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger oneofsArray_Count;
 
-// The protocol buffer options.
+/// The protocol buffer options.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray;
+/// The number of items in @c optionsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger optionsArray_Count;
 
-// The source context.
-@property(nonatomic, readwrite) BOOL hasSourceContext;
+/// The source context.
 @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext;
+/// Test to see if @c sourceContext has been set.
+@property(nonatomic, readwrite) BOOL hasSourceContext;
 
-// The source syntax.
+/// The source syntax.
 @property(nonatomic, readwrite) GPBSyntax syntax;
 
 @end
 
+/// Fetches the raw value of a @c GPBType's @c syntax property, even
+/// if the value was not defined by the enum at the time the code was generated.
 int32_t GPBType_Syntax_RawValue(GPBType *message);
+/// Sets the raw value of an @c GPBType's @c syntax property, allowing
+/// it to be set to a value that was not defined by the enum at the time the code
+/// was generated.
 void SetGPBType_Syntax_RawValue(GPBType *message, int32_t value);
 
 #pragma mark - GPBField
@@ -191,48 +217,59 @@ typedef GPB_ENUM(GPBField_FieldNumber) {
   GPBField_FieldNumber_DefaultValue = 11,
 };
 
-// A single field of a message type.
+/// A single field of a message type.
 @interface GPBField : GPBMessage
 
-// The field type.
+/// The field type.
 @property(nonatomic, readwrite) GPBField_Kind kind;
 
-// The field cardinality.
+/// The field cardinality.
 @property(nonatomic, readwrite) GPBField_Cardinality cardinality;
 
-// The field number.
+/// The field number.
 @property(nonatomic, readwrite) int32_t number;
 
-// The field name.
+/// The field name.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *name;
 
-// The field type URL, without the scheme, for message or enumeration
-// types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.
+/// The field type URL, without the scheme, for message or enumeration
+/// types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL;
 
-// The index of the field type in `Type.oneofs`, for message or enumeration
-// types. The first type has index 1; zero means the type is not in the list.
+/// The index of the field type in `Type.oneofs`, for message or enumeration
+/// types. The first type has index 1; zero means the type is not in the list.
 @property(nonatomic, readwrite) int32_t oneofIndex;
 
-// Whether to use alternative packed wire representation.
+/// Whether to use alternative packed wire representation.
 @property(nonatomic, readwrite) BOOL packed;
 
-// The protocol buffer options.
+/// The protocol buffer options.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray;
+/// The number of items in @c optionsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger optionsArray_Count;
 
-// The field JSON name.
+/// The field JSON name.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *jsonName;
 
-// The string value of the default value of this field. Proto2 syntax only.
+/// The string value of the default value of this field. Proto2 syntax only.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *defaultValue;
 
 @end
 
+/// Fetches the raw value of a @c GPBField's @c kind property, even
+/// if the value was not defined by the enum at the time the code was generated.
 int32_t GPBField_Kind_RawValue(GPBField *message);
+/// Sets the raw value of an @c GPBField's @c kind property, allowing
+/// it to be set to a value that was not defined by the enum at the time the code
+/// was generated.
 void SetGPBField_Kind_RawValue(GPBField *message, int32_t value);
 
+/// Fetches the raw value of a @c GPBField's @c cardinality property, even
+/// if the value was not defined by the enum at the time the code was generated.
 int32_t GPBField_Cardinality_RawValue(GPBField *message);
+/// Sets the raw value of an @c GPBField's @c cardinality property, allowing
+/// it to be set to a value that was not defined by the enum at the time the code
+/// was generated.
 void SetGPBField_Cardinality_RawValue(GPBField *message, int32_t value);
 
 #pragma mark - GPBEnum
@@ -245,30 +282,38 @@ typedef GPB_ENUM(GPBEnum_FieldNumber) {
   GPBEnum_FieldNumber_Syntax = 5,
 };
 
-// Enum type definition.
+/// Enum type definition.
 @interface GPBEnum : GPBMessage
 
-// Enum type name.
+/// Enum type name.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *name;
 
-// Enum value definitions.
+/// Enum value definitions.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBEnumValue*> *enumvalueArray;
+/// The number of items in @c enumvalueArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger enumvalueArray_Count;
 
-// Protocol buffer options.
+/// Protocol buffer options.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray;
+/// The number of items in @c optionsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger optionsArray_Count;
 
-// The source context.
-@property(nonatomic, readwrite) BOOL hasSourceContext;
+/// The source context.
 @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext;
+/// Test to see if @c sourceContext has been set.
+@property(nonatomic, readwrite) BOOL hasSourceContext;
 
-// The source syntax.
+/// The source syntax.
 @property(nonatomic, readwrite) GPBSyntax syntax;
 
 @end
 
+/// Fetches the raw value of a @c GPBEnum's @c syntax property, even
+/// if the value was not defined by the enum at the time the code was generated.
 int32_t GPBEnum_Syntax_RawValue(GPBEnum *message);
+/// Sets the raw value of an @c GPBEnum's @c syntax property, allowing
+/// it to be set to a value that was not defined by the enum at the time the code
+/// was generated.
 void SetGPBEnum_Syntax_RawValue(GPBEnum *message, int32_t value);
 
 #pragma mark - GPBEnumValue
@@ -279,17 +324,18 @@ typedef GPB_ENUM(GPBEnumValue_FieldNumber) {
   GPBEnumValue_FieldNumber_OptionsArray = 3,
 };
 
-// Enum value definition.
+/// Enum value definition.
 @interface GPBEnumValue : GPBMessage
 
-// Enum value name.
+/// Enum value name.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *name;
 
-// Enum value number.
+/// Enum value number.
 @property(nonatomic, readwrite) int32_t number;
 
-// Protocol buffer options.
+/// Protocol buffer options.
 @property(nonatomic, readwrite, strong, null_resettable) NSMutableArray<GPBOption*> *optionsArray;
+/// The number of items in @c optionsArray without causing the array to be created.
 @property(nonatomic, readonly) NSUInteger optionsArray_Count;
 
 @end
@@ -301,16 +347,17 @@ typedef GPB_ENUM(GPBOption_FieldNumber) {
   GPBOption_FieldNumber_Value = 2,
 };
 
-// A protocol buffer option, which can be attached to a message, field,
-// enumeration, etc.
+/// A protocol buffer option, which can be attached to a message, field,
+/// enumeration, etc.
 @interface GPBOption : GPBMessage
 
-// The option's name. For example, `"java_package"`.
+/// The option's name. For example, `"java_package"`.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *name;
 
-// The option's value. For example, `"com.google.protobuf"`.
-@property(nonatomic, readwrite) BOOL hasValue;
+/// The option's value. For example, `"com.google.protobuf"`.
 @property(nonatomic, readwrite, strong, null_resettable) GPBAny *value;
+/// Test to see if @c value has been set.
+@property(nonatomic, readwrite) BOOL hasValue;
 
 @end
 

objectivec/google/protobuf/Wrappers.pbobjc.h

@@ -15,13 +15,15 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - GPBWrappersRoot
 
+/// Exposes the extension registry for this file.
+///
+/// The base class provides:
+/// @code
+///   + (GPBExtensionRegistry *)extensionRegistry;
+/// @endcode
+/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
+/// this file and all files that it depends on.
 @interface GPBWrappersRoot : GPBRootObject
-
-// The base class provides:
-//   + (GPBExtensionRegistry *)extensionRegistry;
-// which is an GPBExtensionRegistry that includes all the extensions defined by
-// this file and all files that it depends on.
-
 @end
 
 #pragma mark - GPBDoubleValue
@@ -30,12 +32,12 @@ typedef GPB_ENUM(GPBDoubleValue_FieldNumber) {
   GPBDoubleValue_FieldNumber_Value = 1,
 };
 
-// Wrapper message for `double`.
-//
-// The JSON representation for `DoubleValue` is JSON number.
+/// Wrapper message for `double`.
+///
+/// The JSON representation for `DoubleValue` is JSON number.
 @interface GPBDoubleValue : GPBMessage
 
-// The double value.
+/// The double value.
 @property(nonatomic, readwrite) double value;
 
 @end
@@ -46,12 +48,12 @@ typedef GPB_ENUM(GPBFloatValue_FieldNumber) {
   GPBFloatValue_FieldNumber_Value = 1,
 };
 
-// Wrapper message for `float`.
-//
-// The JSON representation for `FloatValue` is JSON number.
+/// Wrapper message for `float`.
+///
+/// The JSON representation for `FloatValue` is JSON number.
 @interface GPBFloatValue : GPBMessage
 
-// The float value.
+/// The float value.
 @property(nonatomic, readwrite) float value;
 
 @end
@@ -62,12 +64,12 @@ typedef GPB_ENUM(GPBInt64Value_FieldNumber) {
   GPBInt64Value_FieldNumber_Value = 1,
 };
 
-// Wrapper message for `int64`.
-//
-// The JSON representation for `Int64Value` is JSON string.
+/// Wrapper message for `int64`.
+///
+/// The JSON representation for `Int64Value` is JSON string.
 @interface GPBInt64Value : GPBMessage
 
-// The int64 value.
+/// The int64 value.
 @property(nonatomic, readwrite) int64_t value;
 
 @end
@@ -78,12 +80,12 @@ typedef GPB_ENUM(GPBUInt64Value_FieldNumber) {
   GPBUInt64Value_FieldNumber_Value = 1,
 };
 
-// Wrapper message for `uint64`.
-//
-// The JSON representation for `UInt64Value` is JSON string.
+/// Wrapper message for `uint64`.
+///
+/// The JSON representation for `UInt64Value` is JSON string.
 @interface GPBUInt64Value : GPBMessage
 
-// The uint64 value.
+/// The uint64 value.
 @property(nonatomic, readwrite) uint64_t value;
 
 @end
@@ -94,12 +96,12 @@ typedef GPB_ENUM(GPBInt32Value_FieldNumber) {
   GPBInt32Value_FieldNumber_Value = 1,
 };
 
-// Wrapper message for `int32`.
-//
-// The JSON representation for `Int32Value` is JSON number.
+/// Wrapper message for `int32`.
+///
+/// The JSON representation for `Int32Value` is JSON number.
 @interface GPBInt32Value : GPBMessage
 
-// The int32 value.
+/// The int32 value.
 @property(nonatomic, readwrite) int32_t value;
 
 @end
@@ -110,12 +112,12 @@ typedef GPB_ENUM(GPBUInt32Value_FieldNumber) {
   GPBUInt32Value_FieldNumber_Value = 1,
 };
 
-// Wrapper message for `uint32`.
-//
-// The JSON representation for `UInt32Value` is JSON number.
+/// Wrapper message for `uint32`.
+///
+/// The JSON representation for `UInt32Value` is JSON number.
 @interface GPBUInt32Value : GPBMessage
 
-// The uint32 value.
+/// The uint32 value.
 @property(nonatomic, readwrite) uint32_t value;
 
 @end
@@ -126,12 +128,12 @@ typedef GPB_ENUM(GPBBoolValue_FieldNumber) {
   GPBBoolValue_FieldNumber_Value = 1,
 };
 
-// Wrapper message for `bool`.
-//
-// The JSON representation for `BoolValue` is JSON `true` and `false`.
+/// Wrapper message for `bool`.
+///
+/// The JSON representation for `BoolValue` is JSON `true` and `false`.
 @interface GPBBoolValue : GPBMessage
 
-// The bool value.
+/// The bool value.
 @property(nonatomic, readwrite) BOOL value;
 
 @end
@@ -142,12 +144,12 @@ typedef GPB_ENUM(GPBStringValue_FieldNumber) {
   GPBStringValue_FieldNumber_Value = 1,
 };
 
-// Wrapper message for `string`.
-//
-// The JSON representation for `StringValue` is JSON string.
+/// Wrapper message for `string`.
+///
+/// The JSON representation for `StringValue` is JSON string.
 @interface GPBStringValue : GPBMessage
 
-// The string value.
+/// The string value.
 @property(nonatomic, readwrite, copy, null_resettable) NSString *value;
 
 @end
@@ -158,12 +160,12 @@ typedef GPB_ENUM(GPBBytesValue_FieldNumber) {
   GPBBytesValue_FieldNumber_Value = 1,
 };
 
-// Wrapper message for `bytes`.
-//
-// The JSON representation for `BytesValue` is JSON string.
+/// Wrapper message for `bytes`.
+///
+/// The JSON representation for `BytesValue` is JSON string.
 @interface GPBBytesValue : GPBMessage
 
-// The bytes value.
+/// The bytes value.
 @property(nonatomic, readwrite, copy, null_resettable) NSData *value;
 
 @end

src/google/protobuf/compiler/objectivec/objectivec_enum.cc

@@ -80,10 +80,12 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) {
   if (HasPreservingUnknownEnumSemantics(descriptor_->file())) {
     // Include the unknown value.
     printer->Print(
+      "/// Value used if any message's field encounters a value that is not defined\n"
+      "/// by this enum. The message will also have C functions to get/set the rawValue\n"
+      "/// of the field.\n"
       "$name$_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue,\n",
       "name", name_);
   }
-
   for (int i = 0; i < all_values_.size(); i++) {
     SourceLocation location;
     if (all_values_[i]->GetSourceLocation(&location)) {
@@ -107,6 +109,8 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) {
       "\n"
       "GPBEnumDescriptor *$name$_EnumDescriptor(void);\n"
       "\n"
+      "/// Checks to see if the given value is defined by the enum or was not known at\n"
+      "/// the time this source was generated.\n"
       "BOOL $name$_IsValidValue(int32_t value);\n"
       "\n",
       "name", name_);

src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc

@@ -87,7 +87,12 @@ void EnumFieldGenerator::GenerateCFunctionDeclarations(
 
   printer->Print(
       variables_,
+      "/// Fetches the raw value of a @c $owning_message_class$'s @c $name$ property, even\n"
+      "/// if the value was not defined by the enum at the time the code was generated.\n"
       "int32_t $owning_message_class$_$capitalized_name$_RawValue($owning_message_class$ *message);\n"
+      "/// Sets the raw value of an @c $owning_message_class$'s @c $name$ property, allowing\n"
+      "/// it to be set to a value that was not defined by the enum at the time the code\n"
+      "/// was generated.\n"
       "void Set$owning_message_class$_$capitalized_name$_RawValue($owning_message_class$ *message, int32_t value);\n"
       "\n");
 }

src/google/protobuf/compiler/objectivec/objectivec_field.cc

@@ -270,15 +270,15 @@ void SingleFieldGenerator::GenerateFieldStorageDeclaration(
 void SingleFieldGenerator::GeneratePropertyDeclaration(
     io::Printer* printer) const {
   printer->Print(variables_, "$comments$");
+  printer->Print(
+      variables_,
+      "@property(nonatomic, readwrite) $property_type$ $name$;\n"
+      "\n");
   if (WantsHasProperty()) {
     printer->Print(
         variables_,
         "@property(nonatomic, readwrite) BOOL has$capitalized_name$;\n");
   }
-  printer->Print(
-      variables_,
-      "@property(nonatomic, readwrite) $property_type$ $name$;\n"
-      "\n");
 }
 
 void SingleFieldGenerator::GeneratePropertyImplementation(
@@ -326,14 +326,15 @@ void ObjCObjFieldGenerator::GeneratePropertyDeclaration(
   // conventions (init*, new*, etc.)
 
   printer->Print(variables_, "$comments$");
+  printer->Print(
+      variables_,
+      "@property(nonatomic, readwrite, $property_storage_attribute$, null_resettable) $property_type$ *$name$$storage_attribute$;\n");
   if (WantsHasProperty()) {
     printer->Print(
         variables_,
+        "/// Test to see if @c $name$ has been set.\n"
         "@property(nonatomic, readwrite) BOOL has$capitalized_name$;\n");
   }
-  printer->Print(
-      variables_,
-      "@property(nonatomic, readwrite, $property_storage_attribute$, null_resettable) $property_type$ *$name$$storage_attribute$;\n");
   if (IsInitName(variables_.find("name")->second)) {
     // If property name starts with init we need to annotate it to get past ARC.
     // http://stackoverflow.com/questions/18723226/how-do-i-annotate-an-objective-c-property-with-an-objc-method-family/18723227#18723227
@@ -385,6 +386,7 @@ void RepeatedFieldGenerator::GeneratePropertyDeclaration(
       "$comments$"
       "$array_comment$"
       "@property(nonatomic, readwrite, strong, null_resettable) $array_property_type$ *$name$$storage_attribute$;\n"
+      "/// The number of items in @c $name$ without causing the array to be created.\n"
       "@property(nonatomic, readonly) NSUInteger $name$_Count;\n");
   if (IsInitName(variables_.find("name")->second)) {
     // If property name starts with init we need to annotate it to get past ARC.

src/google/protobuf/compiler/objectivec/objectivec_file.cc

@@ -151,13 +151,15 @@ void FileGenerator::GenerateHeader(io::Printer *printer) {
   printer->Print(
       "#pragma mark - $root_class_name$\n"
       "\n"
+      "/// Exposes the extension registry for this file.\n"
+      "///\n"
+      "/// The base class provides:\n"
+      "/// @code\n"
+      "///   + (GPBExtensionRegistry *)extensionRegistry;\n"
+      "/// @endcode\n"
+      "/// which is a @c GPBExtensionRegistry that includes all the extensions defined by\n"
+      "/// this file and all files that it depends on.\n"
       "@interface $root_class_name$ : GPBRootObject\n"
-      "\n"
-      "// The base class provides:\n"
-      "//   + (GPBExtensionRegistry *)extensionRegistry;\n"
-      "// which is an GPBExtensionRegistry that includes all the extensions defined by\n"
-      "// this file and all files that it depends on.\n"
-      "\n"
       "@end\n"
       "\n",
       "root_class_name", root_class_name_);

src/google/protobuf/compiler/objectivec/objectivec_helpers.cc

@@ -771,16 +771,14 @@ string BuildCommentsString(const SourceLocation& location) {
   while (!lines.empty() && lines.back().empty()) {
     lines.pop_back();
   }
-  string prefix("//");
+  string prefix("///");
   string suffix("\n");
   string final_comments;
   for (int i = 0; i < lines.size(); i++) {
-    // We use $ for delimiters, so replace comments with dollars with
-    // html escaped version.
-    // None of the other compilers handle this (as of this writing) but we
-    // ran into it once, so just to be safe.
+    // HeaderDoc uses '\' and '@' for markers; escape them.
+    const string line = StringReplace(lines[i], "\\", "\\\\", true);
     final_comments +=
-        prefix + StringReplace(lines[i], "$", "&#36;", true) + suffix;
+        prefix + StringReplace(line, "@", "\\@", true) + suffix;
   }
   return final_comments;
 }

src/google/protobuf/compiler/objectivec/objectivec_helpers.h

@@ -146,6 +146,7 @@ string DefaultValue(const FieldDescriptor* field);
 
 string BuildFlagsString(const vector<string>& strings);
 
+// Builds a HeaderDoc style comment out of the comments in the .proto file.
 string BuildCommentsString(const SourceLocation& location);
 
 // Checks the prefix for a given file and outputs any warnings needed, if

src/google/protobuf/compiler/objectivec/objectivec_oneof.cc

@@ -104,6 +104,7 @@ void OneofGenerator::GeneratePublicCasePropertyDeclaration(
 void OneofGenerator::GenerateClearFunctionDeclaration(io::Printer* printer) {
   printer->Print(
       variables_,
+      "/// Clears whatever value was set for the oneof '$name$'.\n"
       "void $owning_message_class$_Clear$capitalized_name$OneOfCase($owning_message_class$ *message);\n");
 }