Merge pull request #1975 from pherl/cp

Cherry pick objc changes into 3.0.0-GA branch

conformance/failure_list_objc.txt

@@ -1,4 +1,4 @@
-# No tests currently failing.
+# All tests currently passing.
 #
-# json input or output tests are skipped (in conformance_objc.m) as mobile
-# platforms don't support json wire format to avoid code bloat.
+# JSON input or output tests are skipped (in conformance_objc.m) as mobile
+# platforms don't support JSON wire format to avoid code bloat.

objectivec/GPBBootstrap.h

@@ -28,11 +28,13 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-// The Objective C runtime has complete enough info that most protos don’t end
-// up using this, so leaving it on is no cost or very little cost.  If you
-// happen to see it causing bloat, this is the way to disable it. If you do
-// need to disable it, try only disabling it for Release builds as having
-// full TextFormat can be useful for debugging.
+/**
+ * The Objective C runtime has complete enough info that most protos don’t end
+ * up using this, so leaving it on is no cost or very little cost.  If you
+ * happen to see it causing bloat, this is the way to disable it. If you do
+ * need to disable it, try only disabling it for Release builds as having
+ * full TextFormat can be useful for debugging.
+ **/
 #ifndef GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS
 #define GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS 0
 #endif
@@ -42,6 +44,7 @@
 #if !__has_feature(objc_fixed_enum)
  #error All supported Xcode versions should support objc_fixed_enum.
 #endif
+
 // If the headers are imported into Objective-C++, we can run into an issue
 // where the defintion of NS_ENUM (really CF_ENUM) changes based on the C++
 // standard that is in effect.  If it isn't C++11 or higher, the definition
@@ -53,19 +56,29 @@
 #else
  #define GPB_ENUM(X) NS_ENUM(int32_t, X)
 #endif
-// GPB_ENUM_FWD_DECLARE is used for forward declaring enums, ex:
-//   GPB_ENUM_FWD_DECLARE(Foo_Enum)
-//   @property (nonatomic) Foo_Enum value;
+
+/**
+ * GPB_ENUM_FWD_DECLARE is used for forward declaring enums, for example:
+ *
+ * ```
+ * GPB_ENUM_FWD_DECLARE(Foo_Enum)
+ * @property (nonatomic) Foo_Enum value;
+ * ```
+ **/
 #define GPB_ENUM_FWD_DECLARE(X) enum X : int32_t
 
-// Based upon CF_INLINE. Forces inlining in release.
+/**
+ * Based upon CF_INLINE. Forces inlining in non DEBUG builds.
+ **/
 #if !defined(DEBUG)
 #define GPB_INLINE static __inline__ __attribute__((always_inline))
 #else
 #define GPB_INLINE static __inline__
 #endif
 
-// For use in public headers that might need to deal with ARC.
+/**
+ * For use in public headers that might need to deal with ARC.
+ **/
 #ifndef GPB_UNSAFE_UNRETAINED
 #if __has_feature(objc_arc)
 #define GPB_UNSAFE_UNRETAINED __unsafe_unretained
@@ -76,10 +89,14 @@
 
 // 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
+//
+// Meant to be used internally by generated code.
 #define GPB_METHOD_FAMILY_NONE __attribute__((objc_method_family(none)))
 
 // The protoc-gen-objc version which works with the current version of the
 // generated Objective C sources.  In general we don't want to change the
 // runtime interfaces (or this version) as it means everything has to be
 // regenerated.
+//
+// Meant to be used internally by generated code.
 #define GOOGLE_PROTOBUF_OBJC_GEN_VERSION 30001

objectivec/GPBCodedInputStream.h

@@ -37,125 +37,194 @@ NS_ASSUME_NONNULL_BEGIN
 
 CF_EXTERN_C_BEGIN
 
-/// GPBCodedInputStream exception name. Exceptions raised from
-/// GPBCodedInputStream contain an underlying error in the userInfo dictionary
-/// under the GPBCodedInputStreamUnderlyingErrorKey key.
+/**
+ * @c GPBCodedInputStream exception name. Exceptions raised from
+ * @c GPBCodedInputStream contain an underlying error in the userInfo dictionary
+ * under the GPBCodedInputStreamUnderlyingErrorKey key.
+ **/
 extern NSString *const GPBCodedInputStreamException;
 
-/// The key under which the underlying NSError from the exception is stored.
+/** The key under which the underlying NSError from the exception is stored. */
 extern NSString *const GPBCodedInputStreamUnderlyingErrorKey;
 
-/// NSError domain used for GPBCodedInputStream errors.
+/** NSError domain used for @c GPBCodedInputStream errors. */
 extern NSString *const GPBCodedInputStreamErrorDomain;
 
-/// Error code for NSError with GPBCodedInputStreamErrorDomain.
+/**
+ * Error code for NSError with @c GPBCodedInputStreamErrorDomain.
+ **/
 typedef NS_ENUM(NSInteger, GPBCodedInputStreamErrorCode) {
-  /// The size does not fit in the remaining bytes to be read.
+  /** The size does not fit in the remaining bytes to be read. */
   GPBCodedInputStreamErrorInvalidSize = -100,
-  /// Attempted to read beyond the subsection limit.
+  /** Attempted to read beyond the subsection limit. */
   GPBCodedInputStreamErrorSubsectionLimitReached = -101,
-  /// The requested subsection limit is invalid.
+  /** The requested subsection limit is invalid. */
   GPBCodedInputStreamErrorInvalidSubsectionLimit = -102,
-  /// Invalid tag read.
+  /** Invalid tag read. */
   GPBCodedInputStreamErrorInvalidTag = -103,
-  /// Invalid UTF-8 character in a string.
+  /** Invalid UTF-8 character in a string. */
   GPBCodedInputStreamErrorInvalidUTF8 = -104,
-  /// Invalid VarInt read.
+  /** Invalid VarInt read. */
   GPBCodedInputStreamErrorInvalidVarInt = -105,
-  /// The maximum recursion depth of messages was exceeded.
+  /** The maximum recursion depth of messages was exceeded. */
   GPBCodedInputStreamErrorRecursionDepthExceeded = -106,
 };
 
 CF_EXTERN_C_END
 
-/// 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.
+/**
+ * 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 @c GPBCodedInputStream is NOT supported.
+ **/
 @interface GPBCodedInputStream : NSObject
 
-/// Creates a new stream wrapping some data.
+/**
+ * Creates a new stream wrapping some data.
+ *
+ * @param data The data to wrap inside the stream.
+ *
+ * @return A newly instanced GPBCodedInputStream.
+ **/
 + (instancetype)streamWithData:(NSData *)data;
 
-/// Initializes a stream wrapping some data.
+/**
+ * Initializes a stream wrapping some data.
+ *
+ * @param data The data to wrap inside the stream.
+ *
+ * @return A newly initialized GPBCodedInputStream.
+ **/
 - (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.
+/**
+ * Attempts 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.
+ *
+ * @return The field tag, or zero if EOF was reached.
+ **/
 - (int32_t)readTag;
 
-/// Read and return a double.
+/**
+ * @return A double read from the stream.
+ **/
 - (double)readDouble;
-/// Read and return a float.
+/**
+ * @return A float read from the stream.
+ **/
 - (float)readFloat;
-/// Read and return a uint64.
+/**
+ * @return A uint64 read from the stream.
+ **/
 - (uint64_t)readUInt64;
-/// Read and return a uint32.
+/**
+ * @return A uint32 read from the stream.
+ **/
 - (uint32_t)readUInt32;
-/// Read and return an int64.
+/**
+ * @return An int64 read from the stream.
+ **/
 - (int64_t)readInt64;
-/// Read and return an int32.
+/**
+ * @return An int32 read from the stream.
+ **/
 - (int32_t)readInt32;
-/// Read and return a fixed64.
+/**
+ * @return A fixed64 read from the stream.
+ **/
 - (uint64_t)readFixed64;
-/// Read and return a fixed32.
+/**
+ * @return A fixed32 read from the stream.
+ **/
 - (uint32_t)readFixed32;
-/// Read and return an enum (int).
+/**
+ * @return An enum read from the stream.
+ **/
 - (int32_t)readEnum;
-/// Read and return a sfixed32.
+/**
+ * @return A sfixed32 read from the stream.
+ **/
 - (int32_t)readSFixed32;
-/// Read and return a sfixed64.
+/**
+ * @return A fixed64 read from the stream.
+ **/
 - (int64_t)readSFixed64;
-/// Read and return a sint32.
+/**
+ * @return A sint32 read from the stream.
+ **/
 - (int32_t)readSInt32;
-/// Read and return a sint64.
+/**
+ * @return A sint64 read from the stream.
+ **/
 - (int64_t)readSInt64;
-/// Read and return a boolean.
+/**
+ * @return A boolean read from the stream.
+ **/
 - (BOOL)readBool;
-/// Read and return a string.
+/**
+ * @return A string read from the stream.
+ **/
 - (NSString *)readString;
-/// Read and return length delimited data.
+/**
+ * @return Data read from the stream.
+ **/
 - (NSData *)readBytes;
 
-/// 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 @c message.
+/**
+ * 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;
 
-/// 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.
+/**
+ * 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;
 
-/// Check to see if the logical end of the stream has been reached.
-///
-/// This can return NO when there is no more data, but the current parsing
-/// expected more data.
+/**
+ * Check to see if the logical end of the stream has been reached.
+ *
+ * @note This can return NO when there is no more data, but the current parsing
+ *       expected more data.
+ *
+ * @return YES if the logical end of the stream has been reached, NO otherwise.
+ **/
 - (BOOL)isAtEnd;
 
-/// The offset into the stream.
+/**
+ * @return The offset into the stream.
+ **/
 - (size_t)position;
 
-/// 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.
+/**
+ * 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.
+ *
+ * @exception NSParseErrorException If the value does not match the last tag.
+ *
+ * @param expected The tag that was expected.
+ **/
 - (void)checkLastTagWas:(int32_t)expected;
 
 @end

objectivec/GPBCodedOutputStream.h

@@ -46,63 +46,122 @@
 
 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.
+/**
+ * Writes out protocol message fields.
+ *
+ * The common uses of protocol buffers shouldn't need to use this class.
+ * GPBMessage's provide a -data method that will serialize the message for you.
+ *
+ * @note Subclassing of GPBCodedOutputStream is NOT supported.
+ **/
 @interface GPBCodedOutputStream : NSObject
 
-/// 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.
+/**
+ * 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.
+ *
+ * @param data The data where the stream will be written to.
+ *
+ * @return A newly instanced GPBCodedOutputStream.
+ **/
 + (instancetype)streamWithData:(NSMutableData *)data;
 
-/// Creates a stream to write into the given @c NSOutputStream.
+/**
+ * Creates a stream to write into the given NSOutputStream.
+ *
+ * @param output The output stream where the stream will be written to.
+ *
+ * @return A newly instanced GPBCodedOutputStream.
+ **/
 + (instancetype)streamWithOutputStream:(NSOutputStream *)output;
 
-/// 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.
+/**
+ * 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.
+ *
+ * @param data The data where the stream will be written to.
+ *
+ * @return A newly initialized GPBCodedOutputStream.
+ **/
 - (instancetype)initWithData:(NSMutableData *)data;
 
-/// Initializes a stream to write into the given @c NSOutputStream.
+/**
+ * Initializes a stream to write into the given @c NSOutputStream.
+ *
+ * @param output The output stream where the stream will be written to.
+ *
+ * @return A newly initialized GPBCodedOutputStream.
+ **/
 - (instancetype)initWithOutputStream:(NSOutputStream *)output;
 
-/// Flush any buffered data out.
+/**
+ * Flush any buffered data out.
+ **/
 - (void)flush;
 
-/// Write the raw byte out.
+/**
+ * Write the raw byte out.
+ *
+ * @param value The value to write 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.
+/**
+ * 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.
+/**
+ * Write a 32bit value out in little endian format.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeRawLittleEndian32:(int32_t)value;
-/// Write a 64bit value out in little endian format.
+/**
+ * Write a 64bit value out in little endian format.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeRawLittleEndian64:(int64_t)value;
 
-/// Write a 32bit value out in varint format.
+/**
+ * Write a 32bit value out in varint format.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeRawVarint32:(int32_t)value;
-/// Write a 64bit value out in varint format.
+/**
+ * Write a 64bit value out in varint format.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeRawVarint64:(int64_t)value;
 
-/// Write a size_t out as a 32bit varint value.
-///
-/// @note 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.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeRawVarintSizeTAs32:(size_t)value;
 
-/// Writes the contents of an @c NSData out.
+/**
+ * Writes the contents of an NSData out.
+ *
+ * @param data The data to write 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.
+/**
+ * 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;
@@ -110,179 +169,471 @@ 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.
+/**
+ * Write a double for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeDouble:(int32_t)fieldNumber value:(double)value;
-/// Write a packed array of double for the given field number.
+/**
+ * Write a packed array of double for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeDoubleArray:(int32_t)fieldNumber
                   values:(GPBDoubleArray *)values
                      tag:(uint32_t)tag;
-/// Write a double without any tag.
+/**
+ * Write a double without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeDoubleNoTag:(double)value;
 
-/// Write a float for the given field number.
+/**
+ * Write a float for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeFloat:(int32_t)fieldNumber value:(float)value;
-/// Write a packed array of float for the given field number.
+/**
+ * Write a packed array of float for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeFloatArray:(int32_t)fieldNumber
                  values:(GPBFloatArray *)values
                     tag:(uint32_t)tag;
-/// Write a float without any tag.
+/**
+ * Write a float without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeFloatNoTag:(float)value;
 
-/// Write a uint64_t for the given field number.
+/**
+ * Write a uint64_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeUInt64:(int32_t)fieldNumber value:(uint64_t)value;
-/// Write a packed array of uint64_t for the given field number.
+/**
+ * Write a packed array of uint64_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeUInt64Array:(int32_t)fieldNumber
                   values:(GPBUInt64Array *)values
                      tag:(uint32_t)tag;
-/// Write a uint64_t without any tag.
+/**
+ * Write a uint64_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeUInt64NoTag:(uint64_t)value;
 
-/// Write a int64_t for the given field number.
+/**
+ * Write a int64_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeInt64:(int32_t)fieldNumber value:(int64_t)value;
-/// Write a packed array of int64_t for the given field number.
+/**
+ * Write a packed array of int64_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeInt64Array:(int32_t)fieldNumber
                  values:(GPBInt64Array *)values
                     tag:(uint32_t)tag;
-/// Write a int64_t without any tag.
+/**
+ * Write a int64_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeInt64NoTag:(int64_t)value;
 
-/// Write a int32_t for the given field number.
+/**
+ * Write a int32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeInt32:(int32_t)fieldNumber value:(int32_t)value;
-/// Write a packed array of int32_t for the given field number.
+/**
+ * Write a packed array of int32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeInt32Array:(int32_t)fieldNumber
                  values:(GPBInt32Array *)values
                     tag:(uint32_t)tag;
-/// Write a int32_t without any tag.
+/**
+ * Write a int32_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeInt32NoTag:(int32_t)value;
 
-/// Write a uint32_t for the given field number.
+/**
+ * Write a uint32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeUInt32:(int32_t)fieldNumber value:(uint32_t)value;
-/// Write a packed array of uint32_t for the given field number.
+/**
+ * Write a packed array of uint32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeUInt32Array:(int32_t)fieldNumber
                   values:(GPBUInt32Array *)values
                      tag:(uint32_t)tag;
-/// Write a uint32_t without any tag.
+/**
+ * Write a uint32_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeUInt32NoTag:(uint32_t)value;
 
-/// Write a uint64_t for the given field number.
+/**
+ * Write a uint64_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeFixed64:(int32_t)fieldNumber value:(uint64_t)value;
-/// Write a packed array of uint64_t for the given field number.
+/**
+ * Write a packed array of uint64_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeFixed64Array:(int32_t)fieldNumber
                    values:(GPBUInt64Array *)values
                       tag:(uint32_t)tag;
-/// Write a uint64_t without any tag.
+/**
+ * Write a uint64_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeFixed64NoTag:(uint64_t)value;
 
-/// Write a uint32_t for the given field number.
+/**
+ * Write a uint32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeFixed32:(int32_t)fieldNumber value:(uint32_t)value;
-/// Write a packed array of uint32_t for the given field number.
+/**
+ * Write a packed array of uint32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeFixed32Array:(int32_t)fieldNumber
                    values:(GPBUInt32Array *)values
                       tag:(uint32_t)tag;
-/// Write a uint32_t without any tag.
+/**
+ * Write a uint32_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeFixed32NoTag:(uint32_t)value;
 
-/// Write a int32_t for the given field number.
+/**
+ * Write a int32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeSInt32:(int32_t)fieldNumber value:(int32_t)value;
-/// Write a packed array of int32_t for the given field number.
+/**
+ * Write a packed array of int32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeSInt32Array:(int32_t)fieldNumber
                   values:(GPBInt32Array *)values
                      tag:(uint32_t)tag;
-/// Write a int32_t without any tag.
+/**
+ * Write a int32_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeSInt32NoTag:(int32_t)value;
 
-/// Write a int64_t for the given field number.
+/**
+ * Write a int64_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeSInt64:(int32_t)fieldNumber value:(int64_t)value;
-/// Write a packed array of int64_t for the given field number.
+/**
+ * Write a packed array of int64_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeSInt64Array:(int32_t)fieldNumber
                   values:(GPBInt64Array *)values
                      tag:(uint32_t)tag;
-/// Write a int64_t without any tag.
+/**
+ * Write a int64_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeSInt64NoTag:(int64_t)value;
 
-/// Write a int64_t for the given field number.
+/**
+ * Write a int64_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeSFixed64:(int32_t)fieldNumber value:(int64_t)value;
-/// Write a packed array of int64_t for the given field number.
+/**
+ * Write a packed array of int64_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeSFixed64Array:(int32_t)fieldNumber
                     values:(GPBInt64Array *)values
                        tag:(uint32_t)tag;
-/// Write a int64_t without any tag.
+/**
+ * Write a int64_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeSFixed64NoTag:(int64_t)value;
 
-/// Write a int32_t for the given field number.
+/**
+ * Write a int32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeSFixed32:(int32_t)fieldNumber value:(int32_t)value;
-/// Write a packed array of int32_t for the given field number.
+/**
+ * Write a packed array of int32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeSFixed32Array:(int32_t)fieldNumber
                     values:(GPBInt32Array *)values
                        tag:(uint32_t)tag;
-/// Write a int32_t without any tag.
+/**
+ * Write a int32_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeSFixed32NoTag:(int32_t)value;
 
-/// Write a BOOL for the given field number.
+/**
+ * Write a BOOL for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeBool:(int32_t)fieldNumber value:(BOOL)value;
-/// Write a packed array of BOOL for the given field number.
+/**
+ * Write a packed array of BOOL for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeBoolArray:(int32_t)fieldNumber
                 values:(GPBBoolArray *)values
                    tag:(uint32_t)tag;
-/// Write a BOOL without any tag.
+/**
+ * Write a BOOL without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeBoolNoTag:(BOOL)value;
 
-/// Write a int32_t for the given field number.
+/**
+ * Write a int32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeEnum:(int32_t)fieldNumber value:(int32_t)value;
-/// Write a packed array of int32_t for the given field number.
+/**
+ * Write a packed array of int32_t for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ * @param tag         The tag assigned to the values.
+ **/
 - (void)writeEnumArray:(int32_t)fieldNumber
                 values:(GPBEnumArray *)values
                    tag:(uint32_t)tag;
-/// Write a int32_t without any tag.
+/**
+ * Write a int32_t without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeEnumNoTag:(int32_t)value;
 
-/// Write a NSString for the given field number.
+/**
+ * Write a NSString for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeString:(int32_t)fieldNumber value:(NSString *)value;
-/// Write an array of NSString for the given field number.
+/**
+ * Write an array of NSString for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ **/
 - (void)writeStringArray:(int32_t)fieldNumber values:(NSArray<NSString*> *)values;
-/// Write a NSString without any tag.
+/**
+ * Write a NSString without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeStringNoTag:(NSString *)value;
 
-/// Write a GPBMessage for the given field number.
+/**
+ * Write a GPBMessage for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeMessage:(int32_t)fieldNumber value:(GPBMessage *)value;
-/// Write an array of GPBMessage for the given field number.
+/**
+ * Write an array of GPBMessage for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ **/
 - (void)writeMessageArray:(int32_t)fieldNumber values:(NSArray<GPBMessage*> *)values;
-/// Write a GPBMessage without any tag.
+/**
+ * Write a GPBMessage without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeMessageNoTag:(GPBMessage *)value;
 
-/// Write a NSData for the given field number.
+/**
+ * Write a NSData for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeBytes:(int32_t)fieldNumber value:(NSData *)value;
-/// Write an array of NSData for the given field number.
+/**
+ * Write an array of NSData for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ **/
 - (void)writeBytesArray:(int32_t)fieldNumber values:(NSArray<NSData*> *)values;
-/// Write a NSData without any tag.
+/**
+ * Write a NSData without any tag.
+ *
+ * @param value The value to write out.
+ **/
 - (void)writeBytesNoTag:(NSData *)value;
 
-/// Write a GPBMessage for the given field number.
+/**
+ * Write a GPBMessage for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeGroup:(int32_t)fieldNumber
              value:(GPBMessage *)value;
-/// Write an array of GPBMessage for the given field number.
+/**
+ * Write an array of GPBMessage for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ **/
 - (void)writeGroupArray:(int32_t)fieldNumber values:(NSArray<GPBMessage*> *)values;
-/// Write a GPBMessage without any tag (but does write the endGroup tag).
+/**
+ * Write a GPBMessage without any tag (but does write the endGroup tag).
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeGroupNoTag:(int32_t)fieldNumber
                   value:(GPBMessage *)value;
 
-/// Write a GPBUnknownFieldSet for the given field number.
+/**
+ * Write a GPBUnknownFieldSet for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (void)writeUnknownGroup:(int32_t)fieldNumber
                     value:(GPBUnknownFieldSet *)value;
-/// Write an array of GPBUnknownFieldSet for the given field number.
+/**
+ * Write an array of GPBUnknownFieldSet for the given field number.
+ *
+ * @param fieldNumber The field number assigned to the values.
+ * @param values      The values to write out.
+ **/
 - (void)writeUnknownGroupArray:(int32_t)fieldNumber values:(NSArray<GPBUnknownFieldSet*> *)values;
-/// Write a GPBUnknownFieldSet without any tag (but does write the endGroup tag).
+/**
+ * Write a GPBUnknownFieldSet without any tag (but does write the endGroup tag).
+ *
+ * @param fieldNumber The field number assigned to the value.
+ * @param value       The value to write out.
+ **/
 - (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.
+
+@param fieldNumber The extension field number to write out.
+@param value       The message from where to get the extension.
+*/
 - (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.
+
+@param fieldNumber The extension field number to write out.
+@param value       The raw message from where to get the extension.
+*/
 - (void)writeRawMessageSetExtension:(int32_t)fieldNumber value:(NSData *)value;
 
 @end
@@ -291,32 +642,76 @@ 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.
+//%/**
+//% * Write a TYPE for the given field number.
+//% *
+//% * @param fieldNumber The field number assigned to the value.
+//% * @param value       The value to write out.
+//% **/
 //%- (void)write##NAME:(int32_t)fieldNumber value:(TYPE)value;
-//%/// Write a packed array of TYPE for the given field number.
+//%/**
+//% * Write a packed array of TYPE for the given field number.
+//% *
+//% * @param fieldNumber The field number assigned to the values.
+//% * @param values      The values to write out.
+//% * @param tag         The tag assigned to the values.
+//% **/
 //%- (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.
+//%/**
+//% * Write a TYPE without any tag.
+//% *
+//% * @param value The value to write out.
+//% **/
 //%- (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.
+//%/**
+//% * Write a TYPE for the given field number.
+//% *
+//% * @param fieldNumber The field number assigned to the value.
+//% * @param value       The value to write out.
+//% **/
 //%- (void)write##NAME:(int32_t)fieldNumber value:(TYPE *)value;
-//%/// Write an array of TYPE for the given field number.
+//%/**
+//% * Write an array of TYPE for the given field number.
+//% *
+//% * @param fieldNumber The field number assigned to the values.
+//% * @param values      The values to write out.
+//% **/
 //%- (void)write##NAME##Array:(int32_t)fieldNumber values:(NSArray<##TYPE##*> *)values;
-//%/// Write a TYPE without any tag.
+//%/**
+//% * Write a TYPE without any tag.
+//% *
+//% * @param value The value to write out.
+//% **/
 //%- (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.
+//%/**
+//% * Write a TYPE for the given field number.
+//% *
+//% * @param fieldNumber The field number assigned to the value.
+//% * @param value       The value to write out.
+//% **/
 //%- (void)write##NAME:(int32_t)fieldNumber
 //%       NAME$S value:(TYPE *)value;
-//%/// Write an array of TYPE for the given field number.
+//%/**
+//% * Write an array of TYPE for the given field number.
+//% *
+//% * @param fieldNumber The field number assigned to the values.
+//% * @param values      The values to write out.
+//% **/
 //%- (void)write##NAME##Array:(int32_t)fieldNumber values:(NSArray<##TYPE##*> *)values;
-//%/// Write a TYPE without any tag (but does write the endGroup tag).
+//%/**
+//% * Write a TYPE without any tag (but does write the endGroup tag).
+//% *
+//% * @param fieldNumber The field number assigned to the value.
+//% * @param value       The value to write out.
+//% **/
 //%- (void)write##NAME##NoTag:(int32_t)fieldNumber
 //%            NAME$S value:(TYPE *)value;
 //%

objectivec/GPBCodedOutputStream.m

@@ -144,22 +144,6 @@ static void GPBWriteRawLittleEndian64(GPBOutputBufferState *state,
   GPBWriteRawByte(state, (int32_t)(value >> 56) & 0xFF);
 }
 
-#if defined(DEBUG) && DEBUG && !defined(NS_BLOCK_ASSERTIONS)
-+ (void)load {
-  // This test exists to verify that CFStrings with embedded NULLs will work
-  // for us. If this Assert fails, all code below that depends on
-  // CFStringGetCStringPtr will NOT work properly on strings that contain
-  // embedded NULLs, and we do get that in some protobufs.
-  // Note that this will not be compiled in release.
-  // We didn't feel that just keeping it in a unit test was sufficient because
-  // the Protobuf unit tests are only run when somebody is actually working
-  // on protobufs.
-  CFStringRef zeroTest = CFSTR("Test\0String");
-  const char *cString = CFStringGetCStringPtr(zeroTest, kCFStringEncodingUTF8);
-  NSAssert(cString == NULL, @"Serious Error");
-}
-#endif  // DEBUG && !defined(NS_BLOCK_ASSERTIONS)
-
 - (void)dealloc {
   [self flush];
   [state_.output close];
@@ -282,19 +266,15 @@ static void GPBWriteRawLittleEndian64(GPBOutputBufferState *state,
 }
 
 - (void)writeStringNoTag:(const NSString *)value {
-  // If you are concerned about embedded NULLs see the test in
-  // +load above.
-  const char *quickString =
-      CFStringGetCStringPtr((CFStringRef)value, kCFStringEncodingUTF8);
-  size_t length = (quickString != NULL)
-                      ? strlen(quickString)
-                      : [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding];
+  size_t length = [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding];
   GPBWriteRawVarint32(&state_, (int32_t)length);
-
   if (length == 0) {
     return;
   }
 
+  const char *quickString =
+      CFStringGetCStringPtr((CFStringRef)value, kCFStringEncodingUTF8);
+
   // Fast path: Most strings are short, if the buffer already has space,
   // add to it directly.
   NSUInteger bufferBytesLeft = state_.size - state_.position;
@@ -1038,14 +1018,7 @@ size_t GPBComputeBoolSizeNoTag(BOOL value) {
 }
 
 size_t GPBComputeStringSizeNoTag(NSString *value) {
-  // If you are concerned about embedded NULLs see the test in
-  // +load above.
-  const char *quickString =
-      CFStringGetCStringPtr((CFStringRef)value, kCFStringEncodingUTF8);
-  NSUInteger length =
-      (quickString != NULL)
-          ? strlen(quickString)
-          : [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding];
+  NSUInteger length = [value lengthOfBytesUsingEncoding:NSUTF8StringEncoding];
   return GPBComputeRawVarint32SizeForInteger(length) + length;
 }
 

objectivec/GPBDescriptor.h

@@ -39,104 +39,241 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/** Syntax used in the proto file. */
 typedef NS_ENUM(uint8_t, GPBFileSyntax) {
+  /** Unknown syntax. */
   GPBFileSyntaxUnknown = 0,
+  /** Proto2 syntax. */
   GPBFileSyntaxProto2 = 2,
+  /** Proto3 syntax. */
   GPBFileSyntaxProto3 = 3,
 };
 
+/** Type of proto field. */
 typedef NS_ENUM(uint8_t, GPBFieldType) {
-  GPBFieldTypeSingle,    // optional/required
-  GPBFieldTypeRepeated,  // repeated
-  GPBFieldTypeMap,       // map<K,V>
+  /** Optional/required field. Only valid for proto2 fields. */
+  GPBFieldTypeSingle,
+  /** Repeated field. */
+  GPBFieldTypeRepeated,
+  /** Map field. */
+  GPBFieldTypeMap,
 };
 
+/**
+ * Describes a proto message.
+ **/
 @interface GPBDescriptor : NSObject<NSCopying>
 
+/** Name of the message. */
 @property(nonatomic, readonly, copy) NSString *name;
+/** Fields declared in the message. */
 @property(nonatomic, readonly, strong, nullable) NSArray<GPBFieldDescriptor*> *fields;
+/** Oneofs declared in the message. */
 @property(nonatomic, readonly, strong, nullable) NSArray<GPBOneofDescriptor*> *oneofs;
+/** Extension range declared for the message. */
 @property(nonatomic, readonly, nullable) const GPBExtensionRange *extensionRanges;
+/** Number of extension ranges declared for the message. */
 @property(nonatomic, readonly) uint32_t extensionRangesCount;
+/** Descriptor for the file where the message was defined. */
 @property(nonatomic, readonly, assign) GPBFileDescriptor *file;
 
+/** Whether the message is in wire format or not. */
 @property(nonatomic, readonly, getter=isWireFormat) BOOL wireFormat;
+/** The class of this message. */
 @property(nonatomic, readonly) Class messageClass;
 
+/**
+ * Gets the field for the given number.
+ *
+ * @param fieldNumber The number for the field to get.
+ *
+ * @return The field descriptor for the given number, or nil if not found.
+ **/
 - (nullable GPBFieldDescriptor *)fieldWithNumber:(uint32_t)fieldNumber;
+
+/**
+ * Gets the field for the given name.
+ *
+ * @param name The name for the field to get.
+ *
+ * @return The field descriptor for the given name, or nil if not found.
+ **/
 - (nullable GPBFieldDescriptor *)fieldWithName:(NSString *)name;
+
+/**
+ * Gets the oneof for the given name.
+ *
+ * @param name The name for the oneof to get.
+ *
+ * @return The oneof descriptor for the given name, or nil if not found.
+ **/
 - (nullable GPBOneofDescriptor *)oneofWithName:(NSString *)name;
 
 @end
 
+/**
+ * Describes a proto file.
+ **/
 @interface GPBFileDescriptor : NSObject
 
+/** The package declared in the proto file. */
 @property(nonatomic, readonly, copy) NSString *package;
+/** The syntax of the proto file. */
 @property(nonatomic, readonly) GPBFileSyntax syntax;
 
 @end
 
+/**
+ * Describes a oneof field.
+ **/
 @interface GPBOneofDescriptor : NSObject
+/** Name of the oneof field. */
 @property(nonatomic, readonly) NSString *name;
+/** Fields declared in the oneof. */
 @property(nonatomic, readonly) NSArray<GPBFieldDescriptor*> *fields;
 
+/**
+ * Gets the field for the given number.
+ *
+ * @param fieldNumber The number for the field to get.
+ *
+ * @return The field descriptor for the given number, or nil if not found.
+ **/
 - (nullable GPBFieldDescriptor *)fieldWithNumber:(uint32_t)fieldNumber;
+
+/**
+ * Gets the field for the given name.
+ *
+ * @param name The name for the field to get.
+ *
+ * @return The field descriptor for the given name, or nil if not found.
+ **/
 - (nullable GPBFieldDescriptor *)fieldWithName:(NSString *)name;
+
 @end
 
+/**
+ * Describes a proto field.
+ **/
 @interface GPBFieldDescriptor : NSObject
 
+/** Name of the field. */
 @property(nonatomic, readonly, copy) NSString *name;
+/** Number associated with the field. */
 @property(nonatomic, readonly) uint32_t number;
+/** Data type contained in the field. */
 @property(nonatomic, readonly) GPBDataType dataType;
+/** Whether it has a default value or not. */
 @property(nonatomic, readonly) BOOL hasDefaultValue;
+/** Default value for the field. */
 @property(nonatomic, readonly) GPBGenericValue defaultValue;
+/** Whether this field is required. Only valid for proto2 fields. */
 @property(nonatomic, readonly, getter=isRequired) BOOL required;
+/** Whether this field is optional. */
 @property(nonatomic, readonly, getter=isOptional) BOOL optional;
+/** Type of field (single, repeated, map). */
 @property(nonatomic, readonly) GPBFieldType fieldType;
-// If it is a map, the value type is in -type.
+/** Type of the key if the field is a map. The value's type is -fieldType. */
 @property(nonatomic, readonly) GPBDataType mapKeyDataType;
+/** Whether the field is packable. */
 @property(nonatomic, readonly, getter=isPackable) BOOL packable;
 
+/** The containing oneof if this field is part of one, nil otherwise. */
 @property(nonatomic, readonly, assign, nullable) GPBOneofDescriptor *containingOneof;
 
-// Message properties
+/** Class of the message if the field is of message type. */
 @property(nonatomic, readonly, assign, nullable) Class msgClass;
 
-// Enum properties
+/** Descriptor for the enum if this field is an enum. */
 @property(nonatomic, readonly, strong, nullable) GPBEnumDescriptor *enumDescriptor;
 
+/**
+ * Checks whether the given enum raw value is a valid enum value.
+ *
+ * @param value The raw enum value to check.
+ *
+ * @return YES if value is a valid enum raw value.
+ **/
 - (BOOL)isValidEnumValue:(int32_t)value;
 
-// For now, this will return nil if it doesn't know the name to use for
-// TextFormat.
+/** @return Name for the text format, or nil if not known. */
 - (nullable NSString *)textFormatName;
 
 @end
 
+/**
+ * Describes a proto enum.
+ **/
 @interface GPBEnumDescriptor : NSObject
 
+/** Name of the enum. */
 @property(nonatomic, readonly, copy) NSString *name;
+/** Function that validates that raw values are valid enum values. */
 @property(nonatomic, readonly) GPBEnumValidationFunc enumVerifier;
 
+/**
+ * Returns the enum value name for the given raw enum.
+ *
+ * @param number The raw enum value.
+ *
+ * @return The name of the enum value passed, or nil if not valid.
+ **/
 - (nullable NSString *)enumNameForValue:(int32_t)number;
+
+/**
+ * Gets the enum raw value for the given enum name.
+ *
+ * @param outValue A pointer where the value will be set.
+ * @param name     The enum name for which to get the raw value.
+ *
+ * @return YES if a value was copied into the pointer, NO otherwise.
+ **/
 - (BOOL)getValue:(nullable int32_t *)outValue forEnumName:(NSString *)name;
 
+/**
+ * Returns the text format for the given raw enum value.
+ *
+ * @param number The raw enum value.
+ *
+ * @return The text format name for the raw enum value, or nil if not valid.
+ **/
 - (nullable NSString *)textFormatNameForValue:(int32_t)number;
+
+/**
+ * Gets the enum raw value for the given text format name.
+ *
+ * @param outValue       A pointer where the value will be set.
+ * @param textFormatName The text format name for which to get the raw value.
+ *
+ * @return YES if a value was copied into the pointer, NO otherwise.
+ **/
 - (BOOL)getValue:(nullable int32_t *)outValue forEnumTextFormatName:(NSString *)textFormatName;
 
 @end
 
+/**
+ * Describes a proto extension.
+ **/
 @interface GPBExtensionDescriptor : NSObject<NSCopying>
+/** Field number under which the extension is stored. */
 @property(nonatomic, readonly) uint32_t fieldNumber;
+/** The containing message class, i.e. the class extended by this extension. */
 @property(nonatomic, readonly) Class containingMessageClass;
+/** Data type contained in the extension. */
 @property(nonatomic, readonly) GPBDataType dataType;
+/** Whether the extension is repeated. */
 @property(nonatomic, readonly, getter=isRepeated) BOOL repeated;
+/** Whether the extension is packable. */
 @property(nonatomic, readonly, getter=isPackable) BOOL packable;
+/** The class of the message if the extension is of message type. */
 @property(nonatomic, readonly, assign) Class msgClass;
+/** The singleton name for the extension. */
 @property(nonatomic, readonly) NSString *singletonName;
+/** The enum descriptor if the extension is of enum type. */
 @property(nonatomic, readonly, strong, nullable) GPBEnumDescriptor *enumDescriptor;
+/** The default value for the extension. */
 @property(nonatomic, readonly, nullable) id defaultValue;
+
 @end
 
 NS_ASSUME_NONNULL_END

objectivec/GPBExtensionRegistry.h

@@ -35,45 +35,50 @@
 
 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 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
+/**
+ * A table of known extensions, searchable by name or field number.  When
+ * parsing a protocol message that might have extensions, you must provide a
+ * 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 *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];
+ * [registry addExtension:[OtherMessage neededExtension]]; // Not in MyProtoFile
+ * NSError *parseError;
+ * MyMessage *msg = [MyMessage parseData:data extensionRegistry:registry error:&parseError];
+ * ```
+ **/
 @interface GPBExtensionRegistry : NSObject<NSCopying>
 
-/// Add the given @c GPBExtensionDescriptor to this registry.
-///
-/// @param extension The extension description to add.
+/**
+ * Adds the given 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.
+/**
+ * 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.
+/**
+ * Looks for the extension registered for the given field number on a given
+ * GPBDescriptor.
+ *
+ * @param descriptor  The descriptor to look for a registered extension on.
+ * @param fieldNumber The field number of the extension to look for.
+ *
+ * @return The registered GPBExtensionDescriptor or nil if none was found.
+ **/
 - (nullable GPBExtensionDescriptor *)extensionForDescriptor:(GPBDescriptor *)descriptor
                                                 fieldNumber:(NSInteger)fieldNumber;
 

objectivec/GPBMessage.h

@@ -44,285 +44,404 @@ NS_ASSUME_NONNULL_BEGIN
 
 CF_EXTERN_C_BEGIN
 
-/// NSError domain used for errors.
+/** NSError domain used for errors. */
 extern NSString *const GPBMessageErrorDomain;
 
-/// Error code for NSError with GPBMessageErrorDomain.
+/** Error codes for NSErrors originated in GPBMessage. */
 typedef NS_ENUM(NSInteger, GPBMessageErrorCode) {
-  /// Uncategorized error.
+  /** Uncategorized error. */
   GPBMessageErrorCodeOther = -100,
-  /// A message can't be serialized because it is missing required fields.
+  /** Message couldn't be serialized because it is missing required fields. */
   GPBMessageErrorCodeMissingRequiredField = -101,
 };
 
-/// Key under which the error's reason is stored inside the userInfo dictionary.
+/**
+ * Key under which the GPBMessage error's reason is stored inside the userInfo
+ * dictionary.
+ **/
 extern NSString *const GPBErrorReasonKey;
 
 CF_EXTERN_C_END
 
-/// Base class for all of the generated message classes.
+/**
+ * Base class that each generated message subclasses from.
+ **/
 @interface GPBMessage : NSObject<NSSecureCoding, NSCopying>
-
-// NOTE: If you add a instance method/property to this class that may conflict
-// with methods declared in protos, you need to update objective_helpers.cc.
-// The main cases are methods that take no arguments, or setFoo:/hasFoo: type
-// methods.
-
-/// The unknown fields for this message.
-///
-/// Only messages from proto files declared with "proto2" syntax support unknown
-/// fields. For "proto3" syntax, any unknown fields found while parsing are
-/// dropped.
+ 
+// If you add an instance method/property to this class that may conflict with
+// fields declared in protos, you need to update objective_helpers.cc. The main
+// cases are methods that take no arguments, or setFoo:/hasFoo: type methods.
+
+/**
+ * The set of unknown fields for this message.
+ *
+ * Only messages from proto files declared with "proto2" syntax support unknown
+ * fields. For "proto3" syntax, any unknown fields found while parsing are
+ * dropped.
+ **/
 @property(nonatomic, copy, nullable) GPBUnknownFieldSet *unknownFields;
 
-/// Are all required fields set in the message and all embedded messages.
+/**
+ * Whether the message, along with all submessages, have the required fields
+ * set. This is only applicable for files declared with "proto2" syntax, as
+ * there are no required fields for "proto3" syntax.
+ **/
 @property(nonatomic, readonly, getter=isInitialized) BOOL initialized;
 
-/// Returns an autoreleased instance.
+/**
+ * @return An autoreleased message with the default values set.
+ **/
 + (instancetype)message;
 
-/// Creates a new instance by parsing the data. This method should be sent to
-/// the generated message class that the data should be interpreted as. If
-/// there is an error the method returns nil and the error is returned in
-/// errorPtr (when provided).
-///
-/// @note In DEBUG builds, the parsed message is checked to be sure all required
-///       fields were provided, and the parse will fail if some are missing.
-///
-/// @note The errors returned are likely coming from the domain and codes listed
-///       at the top of this file and GPBCodedInputStream.h.
-///
-/// @param data     The data to parse.
-/// @param errorPtr An optional error pointer to fill in with a failure reason if
-///                 the data can not be parsed.
-///
-/// @return A new instance of the class messaged.
+/**
+ * Creates a new instance by parsing the provided data. This method should be
+ * sent to the generated message class that the data should be interpreted as.
+ * If there is an error the method returns nil and the error is returned in
+ * errorPtr (when provided).
+ *
+ * @note In DEBUG builds, the parsed message is checked to be sure all required
+ *       fields were provided, and the parse will fail if some are missing.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @param data     The data to parse.
+ * @param errorPtr An optional error pointer to fill in with a failure reason if
+ *                 the data can not be parsed.
+ *
+ * @return A new instance of the generated class.
+ **/
 + (nullable instancetype)parseFromData:(NSData *)data error:(NSError **)errorPtr;
 
-/// Creates a new instance by parsing the data. This method should be sent to
-/// the generated message class that the data should be interpreted as. If
-/// there is an error the method returns nil and the error is returned in
-/// errorPtr (when provided).
-///
-/// @note In DEBUG builds, the parsed message is checked to be sure all required
-///       fields were provided, and the parse will fail if some are missing.
-///
-/// @note The errors returned are likely coming from the domain and codes listed
-///       at the top of this file and GPBCodedInputStream.h.
-///
-/// @param data              The data to parse.
-/// @param extensionRegistry The extension registry to use to look up extensions.
-/// @param errorPtr          An optional error pointer to fill in with a failure
-///                          reason if the data can not be parsed.
-///
-/// @return A new instance of the class messaged.
+/**
+ * Creates a new instance by parsing the data. This method should be sent to
+ * the generated message class that the data should be interpreted as. If
+ * there is an error the method returns nil and the error is returned in
+ * errorPtr (when provided).
+ *
+ * @note In DEBUG builds, the parsed message is checked to be sure all required
+ *       fields were provided, and the parse will fail if some are missing.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @param data              The data to parse.
+ * @param extensionRegistry The extension registry to use to look up extensions.
+ * @param errorPtr          An optional error pointer to fill in with a failure
+ *                          reason if the data can not be parsed.
+ *
+ * @return A new instance of the generated class.
+ **/
 + (nullable instancetype)parseFromData:(NSData *)data
                      extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry
                                  error:(NSError **)errorPtr;
 
-/// Creates a new instance by parsing the data from the given input stream. This
-/// method should be sent to the generated message class that the data should
-/// be interpreted as. If there is an error the method returns nil and the error
-/// is returned in errorPtr (when provided).
-///
-/// @note In DEBUG builds, the parsed message is checked to be sure all required
-///       fields were provided, and the parse will fail if some are missing.
-///
-/// @note The errors returned are likely coming from the domain and codes listed
-///       at the top of this file and GPBCodedInputStream.h.
-///
-/// @param input             The stream to read data from.
-/// @param extensionRegistry The extension registry to use to look up extensions.
-/// @param errorPtr          An optional error pointer to fill in with a failure
-///                          reason if the data can not be parsed.
-///
-/// @return A new instance of the class messaged.
+/**
+ * Creates a new instance by parsing the data from the given input stream. This
+ * method should be sent to the generated message class that the data should
+ * be interpreted as. If there is an error the method returns nil and the error
+ * is returned in errorPtr (when provided).
+ *
+ * @note In DEBUG builds, the parsed message is checked to be sure all required
+ *       fields were provided, and the parse will fail if some are missing.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @param input             The stream to read data from.
+ * @param extensionRegistry The extension registry to use to look up extensions.
+ * @param errorPtr          An optional error pointer to fill in with a failure
+ *                          reason if the data can not be parsed.
+ *
+ * @return A new instance of the generated class.
+ **/
 + (nullable instancetype)parseFromCodedInputStream:(GPBCodedInputStream *)input
                                  extensionRegistry:
                                      (nullable GPBExtensionRegistry *)extensionRegistry
                                              error:(NSError **)errorPtr;
 
-/// Creates a new instance by parsing the data from the given input stream. This
-/// method should be sent to the generated message class that the data should
-/// be interpreted as. If there is an error the method returns nil and the error
-/// is returned in errorPtr (when provided).
-///
-/// @note Unlike the parseFrom... methods, this never checks to see if all of
-///       the required fields are set. So this method can be used to reload
-///       messages that may not be complete.
-///
-/// @note The errors returned are likely coming from the domain and codes listed
-///       at the top of this file and GPBCodedInputStream.h.
-///
-/// @param input             The stream to read data from.
-/// @param extensionRegistry The extension registry to use to look up extensions.
-/// @param errorPtr          An optional error pointer to fill in with a failure
-///                          reason if the data can not be parsed.
-///
-/// @return A new instance of the class messaged.
+/**
+ * Creates a new instance by parsing the data from the given input stream. This
+ * method should be sent to the generated message class that the data should
+ * be interpreted as. If there is an error the method returns nil and the error
+ * is returned in errorPtr (when provided).
+ *
+ * @note Unlike the parseFrom... methods, this never checks to see if all of
+ *       the required fields are set. So this method can be used to reload
+ *       messages that may not be complete.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @param input             The stream to read data from.
+ * @param extensionRegistry The extension registry to use to look up extensions.
+ * @param errorPtr          An optional error pointer to fill in with a failure
+ *                          reason if the data can not be parsed.
+ *
+ * @return A new instance of the generated class.
+ **/
 + (nullable instancetype)parseDelimitedFromCodedInputStream:(GPBCodedInputStream *)input
                                           extensionRegistry:
                                               (nullable GPBExtensionRegistry *)extensionRegistry
                                                       error:(NSError **)errorPtr;
 
-/// Initializes an instance by parsing the data. This method should be sent to
-/// the generated message class that the data should be interpreted as. If
-/// there is an error the method returns nil and the error is returned in
-/// errorPtr (when provided).
-///
-/// @note In DEBUG builds, the parsed message is checked to be sure all required
-///       fields were provided, and the parse will fail if some are missing.
-///
-/// @note The errors returned are likely coming from the domain and codes listed
-///       at the top of this file and GPBCodedInputStream.h.
-///
-/// @param data     The data to parse.
-/// @param errorPtr An optional error pointer to fill in with a failure reason if
-///                 the data can not be parsed.
+/**
+ * Initializes an instance by parsing the data. This method should be sent to
+ * the generated message class that the data should be interpreted as. If
+ * there is an error the method returns nil and the error is returned in
+ * errorPtr (when provided).
+ *
+ * @note In DEBUG builds, the parsed message is checked to be sure all required
+ *       fields were provided, and the parse will fail if some are missing.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @param data     The data to parse.
+ * @param errorPtr An optional error pointer to fill in with a failure reason if
+ *                 the data can not be parsed.
+ *
+ * @return An initialized instance of the generated class.
+ **/
 - (nullable instancetype)initWithData:(NSData *)data error:(NSError **)errorPtr;
 
-/// Initializes an instance by parsing the data. This method should be sent to
-/// the generated message class that the data should be interpreted as. If
-/// there is an error the method returns nil and the error is returned in
-/// errorPtr (when provided).
-///
-/// @note In DEBUG builds, the parsed message is checked to be sure all required
-///       fields were provided, and the parse will fail if some are missing.
-///
-/// @note The errors returned are likely coming from the domain and codes listed
-///       at the top of this file and GPBCodedInputStream.h.
-///
-/// @param data              The data to parse.
-/// @param extensionRegistry The extension registry to use to look up extensions.
-/// @param errorPtr          An optional error pointer to fill in with a failure
-///                          reason if the data can not be parsed.
+/**
+ * Initializes an instance by parsing the data. This method should be sent to
+ * the generated message class that the data should be interpreted as. If
+ * there is an error the method returns nil and the error is returned in
+ * errorPtr (when provided).
+ *
+ * @note In DEBUG builds, the parsed message is checked to be sure all required
+ *       fields were provided, and the parse will fail if some are missing.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @param data              The data to parse.
+ * @param extensionRegistry The extension registry to use to look up extensions.
+ * @param errorPtr          An optional error pointer to fill in with a failure
+ *                          reason if the data can not be parsed.
+ *
+ * @return An initialized instance of the generated class.
+ **/
 - (nullable instancetype)initWithData:(NSData *)data
                     extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry
                                 error:(NSError **)errorPtr;
 
-/// Initializes an instance by parsing the data from the given input stream. This
-/// method should be sent to the generated message class that the data should
-/// be interpreted as. If there is an error the method returns nil and the error
-/// is returned in errorPtr (when provided).
-///
-/// @note Unlike the parseFrom... methods, this never checks to see if all of
-///       the required fields are set. So this method can be used to reload
-///       messages that may not be complete.
-///
-/// @note The errors returned are likely coming from the domain and codes listed
-///       at the top of this file and GPBCodedInputStream.h.
-///
-/// @param input             The stream to read data from.
-/// @param extensionRegistry The extension registry to use to look up extensions.
-/// @param errorPtr          An optional error pointer to fill in with a failure
-///                          reason if the data can not be parsed.
+/**
+ * Initializes an instance by parsing the data from the given input stream. This
+ * method should be sent to the generated message class that the data should
+ * be interpreted as. If there is an error the method returns nil and the error
+ * is returned in errorPtr (when provided).
+ *
+ * @note Unlike the parseFrom... methods, this never checks to see if all of
+ *       the required fields are set. So this method can be used to reload
+ *       messages that may not be complete.
+ *
+ * @note The errors returned are likely coming from the domain and codes listed
+ *       at the top of this file and GPBCodedInputStream.h.
+ *
+ * @param input             The stream to read data from.
+ * @param extensionRegistry The extension registry to use to look up extensions.
+ * @param errorPtr          An optional error pointer to fill in with a failure
+ *                          reason if the data can not be parsed.
+ *
+ * @return An initialized instance of the generated class.
+ **/
 - (nullable instancetype)initWithCodedInputStream:(GPBCodedInputStream *)input
                                 extensionRegistry:
                                     (nullable GPBExtensionRegistry *)extensionRegistry
                                             error:(NSError **)errorPtr;
 
-/// Writes out the message to the given output stream.
+/**
+ * Parses the given data as this message's class, and merges those values into
+ * this message.
+ *
+ * @param data              The binary representation of the message to merge.
+ * @param extensionRegistry The extension registry to use to look up extensions.
+ *
+ * @exception GPBCodedInputStreamException Exception thrown when parsing was
+ *                                         unsuccessful.
+ **/
+- (void)mergeFromData:(NSData *)data
+    extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
+
+/**
+ * Merges the fields from another message (of the same type) into this
+ * message.
+ *
+ * @param other Message to merge into this message.
+ **/
+- (void)mergeFrom:(GPBMessage *)other;
+
+/**
+ * Writes out the message to the given coded output stream.
+ *
+ * @param output The coded output stream into which to write the message.
+ **/
 - (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output;
-/// Writes out the message to the given output stream.
+
+/**
+ * Writes out the message to the given output stream.
+ *
+ * @param output The output stream into which to write the message.
+ **/
 - (void)writeToOutputStream:(NSOutputStream *)output;
 
-/// Writes out a varint for the message size followed by the the message to
-/// the given output stream.
+/**
+ * Writes out a varint for the message size followed by the the message to
+ * the given output stream.
+ *
+ * @param output The coded output stream into which to write the message.
+ **/
 - (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output;
-/// Writes out a varint for the message size followed by the the message to
-/// the given output stream.
+
+/**
+ * Writes out a varint for the message size followed by the the message to
+ * the given output stream.
+ *
+ * @param output The output stream into which to write the message.
+ **/
 - (void)writeDelimitedToOutputStream:(NSOutputStream *)output;
 
-/// Serializes the message to a @c NSData.
-///
-/// If there is an error while generating the data, nil is returned.
-///
-/// @note This value is not cached, so if you are using it repeatedly, cache
-///       it yourself.
-///
-/// @note In DEBUG ONLY, the message is also checked for all required field,
-///       if one is missing, nil will be returned.
+/**
+ * Serializes the message to an NSData.
+ *
+ * If there is an error while generating the data, nil is returned.
+ *
+ * @note This value is not cached, so if you are using it repeatedly, cache
+ *       it yourself.
+ *
+ * @note In DEBUG ONLY, the message is also checked for all required field,
+ *       if one is missing, nil will be returned.
+ *
+ * @return The binary representation of the message.
+ **/
 - (nullable NSData *)data;
 
-/// Serializes a varint with the message size followed by the message data,
-/// returning that as a @c NSData.
-///
-/// @note This value is not cached, so if you are using it repeatedly, cache
-///       it yourself.
+/**
+ * Serializes a varint with the message size followed by the message data,
+ * returning that as an NSData.
+ *
+ * @note This value is not cached, so if you are using it repeatedly, it is
+ *       recommended to keep a local copy.
+ *
+ * @return The binary representation of the size along with the message.
+ **/
 - (NSData *)delimitedData;
 
-/// Calculates the size of the object if it were serialized.
-///
-/// This is not a cached value. If you are following a pattern like this:
-/// @code
-///   size_t size = [aMsg serializedSize];
-///   NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)];
-///   [foo writeSize:size];
-///   [foo appendData:[aMsg data]];
-/// @endcode
-/// you would be better doing:
-/// @code
-///   NSData *data = [aMsg data];
-///   NSUInteger size = [aMsg length];
-///   NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)];
-///   [foo writeSize:size];
-///   [foo appendData:data];
-/// @endcode
+/**
+ * Calculates the size of the object if it were serialized.
+ *
+ * This is not a cached value. If you are following a pattern like this:
+ *
+ * ```
+ * size_t size = [aMsg serializedSize];
+ * NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)];
+ * [foo writeSize:size];
+ * [foo appendData:[aMsg data]];
+ * ```
+ *
+ * you would be better doing:
+ *
+ * ```
+ * NSData *data = [aMsg data];
+ * NSUInteger size = [aMsg length];
+ * NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)];
+ * [foo writeSize:size];
+ * [foo appendData:data];
+ * ```
+ *
+ * @return The size of the message in it's binary representation.
+ **/
 - (size_t)serializedSize;
 
-/// Return the descriptor for the message class.
+/**
+ * @return The descriptor for the message class.
+ **/
 + (GPBDescriptor *)descriptor;
-/// Return the descriptor for the message.
+
+/**
+ * Return the descriptor for the message.
+ **/
 - (GPBDescriptor *)descriptor;
 
-/// Returns an array with the currently set GPBExtensionDescriptors.
+/**
+ * @return An array with the extension descriptors that are currently set on the
+ * message.
+ **/
 - (NSArray *)extensionsCurrentlySet;
 
-/// Test to see if the given extension is set on the message.
+/**
+ * Checks whether there is an extension set on the message which matches the
+ * given extension descriptor.
+ *
+ * @param extension Extension descriptor to check if it's set on the message.
+ *
+ * @return Whether the extension is currently set on the message.
+ **/
 - (BOOL)hasExtension:(GPBExtensionDescriptor *)extension;
 
-/// Fetches the given extension's value for this message.
-///
-/// Extensions use boxed values (NSNumbers) for PODs and NSMutableArrays for
-/// repeated fields. If the extension is a Message one will be auto created for you
-/// and returned similar to fields.
+/*
+ * Fetches the given extension's value for this message.
+ *
+ * Extensions use boxed values (NSNumbers) for PODs and NSMutableArrays for
+ * repeated fields. If the extension is a Message one will be auto created for
+ * you and returned similar to fields.
+ *
+ * @param extension The extension descriptor of the extension to fetch.
+ *
+ * @return The extension matching the given descriptor, or nil if none found.
+ **/
 - (nullable id)getExtension:(GPBExtensionDescriptor *)extension;
 
-/// Sets the given extension's value for this message. This is only for single
-/// field extensions (i.e. - not repeated fields).
-///
-/// Extensions use boxed values (@c NSNumbers).
-- (void)setExtension:(GPBExtensionDescriptor *)extension value:(nullable id)value;
-
-/// Adds the given value to the extension for this message. This is only for
-/// repeated field extensions. If the field is a repeated POD type the @c value
-/// is a @c NSNumber.
+/**
+ * Sets the given extension's value for this message. This only applies for
+ * single field extensions (i.e. - not repeated fields).
+ *
+ * Extensions use boxed values (NSNumbers).
+ *
+ * @param extension The extension descriptor under which to set the value.
+ * @param value     The value to be set as the extension.
+ **/
+- (void)setExtension:(GPBExtensionDescriptor *)extension
+               value:(nullable id)value;
+
+/**
+ * Adds the given value to the extension for this message. This only applies
+ * to repeated field extensions. If the field is a repeated POD type, the value
+ * should be an NSNumber.
+ *
+ * @param extension The extension descriptor under which to add the value.
+ * @param value     The value to be added to the repeated extension.
+ **/
 - (void)addExtension:(GPBExtensionDescriptor *)extension value:(id)value;
 
-/// Replaces the given value at an index for the extension on this message. This
-/// is only for repeated field extensions. If the field is a repeated POD type
-/// the @c value is a @c NSNumber.
+/**
+ * Replaces the value at the given index with the given value for the extension
+ * on this message. This only applies to repeated field extensions. If the field
+ * is a repeated POD type, the value is should be an NSNumber.
+ *
+ * @param extension The extension descriptor under which to replace the value.
+ * @param index     The index of the extension to be replaced.
+ * @param value     The value to be replaced in the repeated extension.
+ **/
 - (void)setExtension:(GPBExtensionDescriptor *)extension
                index:(NSUInteger)index
                value:(id)value;
 
-/// Clears the given extension for this message.
+/**
+ * Clears the given extension for this message.
+ *
+ * @param extension The extension descriptor to be cleared from this message.
+ **/
 - (void)clearExtension:(GPBExtensionDescriptor *)extension;
 
-/// Resets all of the fields of this message to their default values.
+/**
+ * Resets all of the fields of this message to their default values.
+ **/
 - (void)clear;
 
-/// Parses a message of this type from the input and merges it with this
-/// message.
-///
-/// @note This will throw if there is an error parsing the data.
-- (void)mergeFromData:(NSData *)data
-    extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
-
-/// Merges the fields from another message (of the same type) into this
-/// message.
-- (void)mergeFrom:(GPBMessage *)other;
-
 @end
 
 NS_ASSUME_NONNULL_END

objectivec/GPBRootObject.h

@@ -34,12 +34,17 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// 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.
+/**
+ * Every generated proto file defines a local "Root" class that exposes a
+ * GPBExtensionRegistry for all the extensions defined by that file and
+ * the files it depends on.
+ **/
 @interface GPBRootObject : NSObject
 
-/// An extension registry for the given file and all the files it depends on.
+/**
+ * @return An extension registry for the given file and all the files it depends
+ * on.
+ **/
 + (GPBExtensionRegistry *)extensionRegistry;
 
 @end

objectivec/GPBRuntimeTypes.h

@@ -36,21 +36,28 @@
 @class GPBMessage;
 @class GPBInt32Array;
 
-// Function used to verify that a given value can be represented by an
-// enum type.
+/**
+ * Verifies that a given value can be represented by an enum type.
+ * */
 typedef BOOL (*GPBEnumValidationFunc)(int32_t);
 
-// Function used to fetch an EnumDescriptor.
+/**
+ * Fetches an EnumDescriptor.
+ * */
 typedef GPBEnumDescriptor *(*GPBEnumDescriptorFunc)(void);
 
-// Magic values used for when an the at runtime to indicate an enum value
-// that wasn't know at compile time.
+/**
+ * Magic value used at runtime to indicate an enum value that wasn't know at
+ * compile time.
+ * */
 enum {
   kGPBUnrecognizedEnumeratorValue = (int32_t)0xFBADBEEF,
 };
 
-// A union for storing all possible Protobuf values.
-// Note that owner is responsible for memory management of object types.
+/**
+ * A union for storing all possible Protobuf values. Note that owner is
+ * responsible for memory management of object types.
+ * */
 typedef union {
   BOOL valueBool;
   int32_t valueInt32;
@@ -65,38 +72,73 @@ typedef union {
   int32_t valueEnum;
 } GPBGenericValue;
 
-// Do not change the order of this enum (or add things to it) without thinking
-// about it very carefully. There are several things that depend on the order.
+/**
+ * Enum listing the possible data types that a field can contain.
+ * 
+ * @note Do not change the order of this enum (or add things to it) without
+ *       thinking about it very carefully. There are several things that depend
+ *       on the order.
+ * */
 typedef NS_ENUM(uint8_t, GPBDataType) {
+  /** Field contains boolean value(s). */
   GPBDataTypeBool = 0,
+  /** Field contains unsigned 4 byte value(s). */
   GPBDataTypeFixed32,
+  /** Field contains signed 4 byte value(s). */
   GPBDataTypeSFixed32,
+  /** Field contains float value(s). */
   GPBDataTypeFloat,
+  /** Field contains unsigned 8 byte value(s). */
   GPBDataTypeFixed64,
+  /** Field contains signed 8 byte value(s). */
   GPBDataTypeSFixed64,
+  /** Field contains double value(s). */
   GPBDataTypeDouble,
+  /**
+   * Field contains variable length value(s). Inefficient for encoding negative
+   * numbers – if your field is likely to have negative values, use
+   * GPBDataTypeSInt32 instead.
+   **/
   GPBDataTypeInt32,
+  /**
+   * Field contains variable length value(s). Inefficient for encoding negative
+   * numbers – if your field is likely to have negative values, use
+   * GPBDataTypeSInt64 instead.
+   **/
   GPBDataTypeInt64,
+  /** Field contains signed variable length integer value(s). */
   GPBDataTypeSInt32,
+  /** Field contains signed variable length integer value(s). */
   GPBDataTypeSInt64,
+  /** Field contains unsigned variable length integer value(s). */
   GPBDataTypeUInt32,
+  /** Field contains unsigned variable length integer value(s). */
   GPBDataTypeUInt64,
+  /** Field contains an arbitrary sequence of bytes. */
   GPBDataTypeBytes,
+  /** Field contains UTF-8 encoded or 7-bit ASCII text. */
   GPBDataTypeString,
+  /** Field contains message type(s). */
   GPBDataTypeMessage,
+  /** Field contains message type(s). */
   GPBDataTypeGroup,
+  /** Field contains enum value(s). */
   GPBDataTypeEnum,
 };
 
 enum {
-  // A count of the number of types in GPBDataType. Separated out from the
-  // GPBDataType enum to avoid warnings regarding not handling
-  // GPBDataType_Count in switch statements.
+  /**
+   * A count of the number of types in GPBDataType. Separated out from the
+   * GPBDataType enum to avoid warnings regarding not handling GPBDataType_Count
+   * in switch statements.
+   **/
   GPBDataType_Count = GPBDataTypeEnum + 1
 };
 
-// An extension range.
+/** An extension range. */
 typedef struct GPBExtensionRange {
-  uint32_t start;  // inclusive
-  uint32_t end;    // exclusive
+  /** Inclusive. */
+  uint32_t start;
+  /** Exclusive. */
+  uint32_t end;
 } GPBExtensionRange;

objectivec/GPBUnknownField.h

@@ -36,52 +36,59 @@
 @class GPBUnknownFieldSet;
 
 NS_ASSUME_NONNULL_BEGIN
-
-/// Store an unknown field. These are used in conjunction with @c GPBUnknownFieldSet
+/**
+ * Store an unknown field. These are used in conjunction with
+ * GPBUnknownFieldSet.
+ **/
 @interface GPBUnknownField : NSObject<NSCopying>
 
-/// The field number the data is stored under.
+/** The field number the data is stored under. */
 @property(nonatomic, readonly, assign) int32_t number;
 
-/// An array of varint values for this field.
+/** An array of varint values for this field. */
 @property(nonatomic, readonly, strong) GPBUInt64Array *varintList;
 
-/// An array of fixed32 values for this field.
+/** An array of fixed32 values for this field. */
 @property(nonatomic, readonly, strong) GPBUInt32Array *fixed32List;
 
-/// An array of fixed64 values for this field.
+/** An array of fixed64 values for this field. */
 @property(nonatomic, readonly, strong) GPBUInt64Array *fixed64List;
 
-/// An array of data values for this field.
+/** An array of data values for this field. */
 @property(nonatomic, readonly, strong) NSArray<NSData*> *lengthDelimitedList;
 
-/// An array of groups of values for this field.
+/** An array of groups of values for this field. */
 @property(nonatomic, readonly, strong) NSArray<GPBUnknownFieldSet*> *groupList;
 
-
-/// Add a value to the varintList.
-///
-/// @param value The value to add.
+/**
+ * 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.
+/**
+ * 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.
+/**
+ * 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.
+/**
+ * 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.
+/**
+ * Add a value to the groupList.
+ *
+ * @param value The value to add.
+ **/
 - (void)addGroup:(GPBUnknownFieldSet *)value;
 
 @end

objectivec/GPBUnknownFieldSet.h

@@ -34,31 +34,48 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// A collection of unknown fields.
+/**
+ * A collection of unknown fields. Fields parsed from the binary representation
+ * of a message that are unknown end up in an instance of this set. This only
+ * applies for files declared with the "proto2" syntax. Files declared with the
+ * "proto3" syntax discard the unknown values.
+ **/
 @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.
+/**
+ * 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.
+/**
+ * Fetches the GPBUnknownField for the given field number.
+ *
+ * @param number The field number to look up.
+ *
+ * @return The GPBUnknownField or nil if none found.
+ **/
 - (nullable GPBUnknownField *)getField:(int32_t)number;
 
-/// Returns the number of fields in this set.
+/**
+ * @return The number of fields in this set.
+ **/
 - (NSUInteger)countOfFields;
 
-/// Adds the given field to the set.
+/**
+ * Adds the given field to the set.
+ *
+ * @param field The field to add to the set.
+ **/
 - (void)addField:(GPBUnknownField *)field;
 
-/// Returns an NSArray of the @c GPBUnknownFields sorted by the field numbers.
-- (NSArray<GPBUnknownField*> *)sortedFields;
+/**
+ * @return An array of the GPBUnknownFields sorted by the field numbers.
+ **/
+- (NSArray<GPBUnknownField *> *)sortedFields;
 
 @end
 

objectivec/GPBUtilities.h

@@ -38,34 +38,58 @@ 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.
-///
-///  @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.
+/**
+ * Generates a string that should be a valid "TextFormat" 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 An NSString with the TextFormat 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.
+/**
+ * Generates a string that should be a valid "TextFormat" 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 An NSString with the TextFormat of the unknown field set.
+ **/
 NSString *GPBTextFormatForUnknownFieldSet(GPBUnknownFieldSet * __nullable unknownSet,
                                           NSString * __nullable lineIndent);
 
-/// Test if the given field is set on a message.
+/**
+ * Checks if the given field number is set on a message.
+ *
+ * @param self        The message to check.
+ * @param fieldNumber The field number to check.
+ *
+ * @return YES if the field number is set on the given message.
+ **/
 BOOL GPBMessageHasFieldNumberSet(GPBMessage *self, uint32_t fieldNumber);
-/// Test if the given field is set on a message.
+
+/**
+ * Checks if the given field is set on a message.
+ *
+ * @param self  The message to check.
+ * @param field The field to check.
+ *
+ * @return YES if the field is set on the given message.
+ **/
 BOOL GPBMessageHasFieldSet(GPBMessage *self, GPBFieldDescriptor *field);
 
-/// Clear the given field of a message.
+/**
+ * Clears the given field for the given message.
+ *
+ * @param self  The message for which to clear the field.
+ * @param field The field to clear.
+ **/
 void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field);
 
 //%PDDM-EXPAND GPB_ACCESSORS()
@@ -73,112 +97,299 @@ void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field);
 
 
 //
-// Get/Set the given field of a message.
+// Get/Set a given field from/to a message.
 //
 
 // Single Fields
 
-/// Gets the value of a bytes field.
+/**
+ * Gets the value of a bytes field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 NSData *GPBGetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a bytes field.
+
+/**
+ * Sets the value of a bytes field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field, NSData *value);
 
-/// Gets the value of a string field.
+/**
+ * Gets the value of a string field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 NSString *GPBGetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a string field.
+
+/**
+ * Sets the value of a string field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field, NSString *value);
 
-/// Gets the value of a message field.
+/**
+ * Gets the value of a message field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 GPBMessage *GPBGetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a message field.
+
+/**
+ * Sets the value of a message field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value);
 
-/// Gets the value of a group field.
+/**
+ * Gets the value of a group field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 GPBMessage *GPBGetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a group field.
+
+/**
+ * Sets the value of a group field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value);
 
-/// Gets the value of a bool field.
+/**
+ * Gets the value of a bool field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 BOOL GPBGetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a bool field.
+
+/**
+ * Sets the value of a bool field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field, BOOL value);
 
-/// Gets the value of an int32 field.
+/**
+ * Gets the value of an int32 field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 int32_t GPBGetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of an int32 field.
+
+/**
+ * Sets the value of an int32 field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
 
-/// Gets the value of an uint32 field.
+/**
+ * Gets the value of an uint32 field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 uint32_t GPBGetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of an uint32 field.
+
+/**
+ * Sets the value of an uint32 field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field, uint32_t value);
 
-/// Gets the value of an int64 field.
+/**
+ * Gets the value of an int64 field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 int64_t GPBGetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of an int64 field.
+
+/**
+ * Sets the value of an int64 field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field, int64_t value);
 
-/// Gets the value of an uint64 field.
+/**
+ * Gets the value of an uint64 field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 uint64_t GPBGetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of an uint64 field.
+
+/**
+ * Sets the value of an uint64 field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field, uint64_t value);
 
-/// Gets the value of a float field.
+/**
+ * Gets the value of a float field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 float GPBGetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a float field.
+
+/**
+ * Sets the value of a float field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field, float value);
 
-/// Gets the value of a double field.
+/**
+ * Gets the value of a double field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 double GPBGetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a double field.
+
+/**
+ * Sets the value of a double field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field, double value);
 
-/// 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.
+/**
+ * Gets 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.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ *
+ * @return The enum value for the given field.
+ **/
 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.
+
+/**
+ * Set the given enum field of a message. You can only set values that are
+ * members of the enum.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The enum value to set in the field.
+ **/
+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.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ *
+ * @return The raw enum value for the given field.
+ **/
 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);
+
+/**
+ * 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.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The raw enum value to set in the field.
+ **/
+void GPBSetMessageRawEnumField(GPBMessage *self,
+                               GPBFieldDescriptor *field,
+                               int32_t value);
 
 // Repeated Fields
 
-/// Gets the value of a repeated field.
-///
-/// The result will be @c GPB*Array or @c NSMutableArray based on the
-/// field's type.
+/**
+ * Gets the value of a repeated field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The repeated field to get.
+ *
+ * @return A GPB*Array or an 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);
+
+/**
+ * Sets the value of a repeated field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param array A GPB*Array or NSMutableArray based on the field's type.
+ **/
+void GPBSetMessageRepeatedField(GPBMessage *self,
+                                GPBFieldDescriptor *field,
+                                id array);
 
 // Map Fields
 
-/// Gets the value of a map<> field.
-///
-/// The result will be @c GPB*Dictionary or @c NSMutableDictionary based on
-/// the field's type.
+/**
+ * Gets the value of a map<> field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The repeated field to get.
+ *
+ * @return A GPB*Dictionary or 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);
+
+/**
+ * Sets the value of a map<> field.
+ *
+ * @param self       The message into which to set the field.
+ * @param field      The field to set.
+ * @param dictionary A GPB*Dictionary or NSMutableDictionary based on the
+ *                   field's type.
+ **/
+void GPBSetMessageMapField(GPBMessage *self,
+                           GPBFieldDescriptor *field,
+                           id dictionary);
 
 //%PDDM-EXPAND-END GPB_ACCESSORS()
 
-// Returns an empty NSData to assign to byte fields when you wish
-// to assign them to empty. Prevents allocating a lot of little [NSData data]
-// objects.
+/**
+ * Returns an empty NSData to assign to byte fields when you wish to assign them
+ * to empty. Prevents allocating a lot of little [NSData data] objects.
+ **/
 NSData *GPBEmptyNSData(void) __attribute__((pure));
 
 NS_ASSUME_NONNULL_END
@@ -189,7 +400,7 @@ CF_EXTERN_C_END
 //%PDDM-DEFINE GPB_ACCESSORS()
 //%
 //%//
-//%// Get/Set the given field of a message.
+//%// Get/Set a given field from/to a message.
 //%//
 //%
 //%// Single Fields
@@ -205,53 +416,119 @@ CF_EXTERN_C_END
 //%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.
+//%/**
+//% * Gets 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.
+//% *
+//% * @param self  The message from which to get the field.
+//% * @param field The field to get.
+//% *
+//% * @return The enum value for the given field.
+//% **/
 //%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.
+//%
+//%/**
+//% * Set the given enum field of a message. You can only set values that are
+//% * members of the enum.
+//% *
+//% * @param self  The message into which to set the field.
+//% * @param field The field to set.
+//% * @param value The enum value to set in the field.
+//% **/
+//%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.
+//% *
+//% * @param self  The message from which to get the field.
+//% * @param field The field to get.
+//% *
+//% * @return The raw enum value for the given field.
+//% **/
 //%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);
+//%
+//%/**
+//% * 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.
+//% *
+//% * @param self  The message into which to set the field.
+//% * @param field The field to set.
+//% * @param value The raw enum value to set in the field.
+//% **/
+//%void GPBSetMessageRawEnumField(GPBMessage *self,
+//%                               GPBFieldDescriptor *field,
+//%                               int32_t value);
 //%
 //%// Repeated Fields
 //%
-//%/// Gets the value of a repeated field.
-//%///
-//%/// The result will be @c GPB*Array or @c NSMutableArray based on the
-//%/// field's type.
+//%/**
+//% * Gets the value of a repeated field.
+//% *
+//% * @param self  The message from which to get the field.
+//% * @param field The repeated field to get.
+//% *
+//% * @return A GPB*Array or an 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);
+//%
+//%/**
+//% * Sets the value of a repeated field.
+//% *
+//% * @param self  The message into which to set the field.
+//% * @param field The field to set.
+//% * @param array A GPB*Array or NSMutableArray based on the field's type.
+//% **/
+//%void GPBSetMessageRepeatedField(GPBMessage *self,
+//%                                GPBFieldDescriptor *field,
+//%                                id array);
 //%
 //%// Map Fields
 //%
-//%/// Gets the value of a map<> field.
-//%///
-//%/// The result will be @c GPB*Dictionary or @c NSMutableDictionary based on
-//%/// the field's type.
+//%/**
+//% * Gets the value of a map<> field.
+//% *
+//% * @param self  The message from which to get the field.
+//% * @param field The repeated field to get.
+//% *
+//% * @return A GPB*Dictionary or 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);
+//%
+//%/**
+//% * Sets the value of a map<> field.
+//% *
+//% * @param self       The message into which to set the field.
+//% * @param field      The field to set.
+//% * @param dictionary A GPB*Dictionary or NSMutableDictionary based on the
+//% *                   field's type.
+//% **/
+//%void GPBSetMessageMapField(GPBMessage *self,
+//%                           GPBFieldDescriptor *field,
+//%                           id dictionary);
 //%
 
 //%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.
+//%/**
+//% * Gets the value of a##AN NAME$L field.
+//% *
+//% * @param self  The message from which to get the field.
+//% * @param field The field to get.
+//% **/
 //%TYPE TisP##GPBGetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field);
-//%/// Sets the value of a##AN NAME$L field.
+//%
+//%/**
+//% * Sets the value of a##AN NAME$L field.
+//% *
+//% * @param self  The message into which to set the field.
+//% * @param field The field to set.
+//% * @param value The to set in the field.
+//% **/
 //%void GPBSetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field, TYPE TisP##value);
 //%

objectivec/GPBUtilities.m

@@ -218,9 +218,10 @@ void GPBMaybeClearOneof(GPBMessage *self, GPBOneofDescriptor *oneof,
 //%  TYPE *typePtr = (TYPE *)&storage[field->description_->offset];
 //%  *typePtr = value;
 //%  // proto2: any value counts as having been set; proto3, it
-//%  // has to be a non zero value.
-//%  BOOL hasValue =
-//%    (syntax == GPBFileSyntaxProto2) || (value != (TYPE)0);
+//%  // has to be a non zero value or be in a oneof.
+//%  BOOL hasValue = ((syntax == GPBFileSyntaxProto2)
+//%                   || (value != (TYPE)0)
+//%                   || (field->containingOneof_ != NULL));
 //%  GPBSetHasIvarField(self, field, hasValue);
 //%  GPBBecomeVisibleToAutocreator(self);
 //%}
@@ -337,8 +338,19 @@ void GPBSetRetainedObjectIvarWithFieldInternal(GPBMessage *self,
     // zero, they are being cleared.
     if ((syntax == GPBFileSyntaxProto3) && !fieldIsMessage &&
         ([value length] == 0)) {
-      setHasValue = NO;
-      value = nil;
+      // Except, if the field was in a oneof, then it still gets recorded as
+      // having been set so the state of the oneof can be serialized back out.
+      if (!oneof) {
+        setHasValue = NO;
+      }
+      if (setHasValue) {
+        NSCAssert(value != nil, @"Should never be setting has for nil");
+      } else {
+        // The value passed in was retained, it must be released since we
+        // aren't saving anything in the field.
+        [value release];
+        value = nil;
+      }
     }
     GPBSetHasIvarField(self, field, setHasValue);
   }
@@ -524,9 +536,10 @@ void GPBSetBoolIvarWithFieldInternal(GPBMessage *self,
   GPBSetHasIvar(self, (int32_t)(fieldDesc->offset), fieldDesc->number, value);
 
   // proto2: any value counts as having been set; proto3, it
-  // has to be a non zero value.
-  BOOL hasValue =
-    (syntax == GPBFileSyntaxProto2) || (value != (BOOL)0);
+  // has to be a non zero value or be in a oneof.
+  BOOL hasValue = ((syntax == GPBFileSyntaxProto2)
+                   || (value != (BOOL)0)
+                   || (field->containingOneof_ != NULL));
   GPBSetHasIvarField(self, field, hasValue);
   GPBBecomeVisibleToAutocreator(self);
 }
@@ -573,9 +586,10 @@ void GPBSetInt32IvarWithFieldInternal(GPBMessage *self,
   int32_t *typePtr = (int32_t *)&storage[field->description_->offset];
   *typePtr = value;
   // proto2: any value counts as having been set; proto3, it
-  // has to be a non zero value.
-  BOOL hasValue =
-    (syntax == GPBFileSyntaxProto2) || (value != (int32_t)0);
+  // has to be a non zero value or be in a oneof.
+  BOOL hasValue = ((syntax == GPBFileSyntaxProto2)
+                   || (value != (int32_t)0)
+                   || (field->containingOneof_ != NULL));
   GPBSetHasIvarField(self, field, hasValue);
   GPBBecomeVisibleToAutocreator(self);
 }
@@ -622,9 +636,10 @@ void GPBSetUInt32IvarWithFieldInternal(GPBMessage *self,
   uint32_t *typePtr = (uint32_t *)&storage[field->description_->offset];
   *typePtr = value;
   // proto2: any value counts as having been set; proto3, it
-  // has to be a non zero value.
-  BOOL hasValue =
-    (syntax == GPBFileSyntaxProto2) || (value != (uint32_t)0);
+  // has to be a non zero value or be in a oneof.
+  BOOL hasValue = ((syntax == GPBFileSyntaxProto2)
+                   || (value != (uint32_t)0)
+                   || (field->containingOneof_ != NULL));
   GPBSetHasIvarField(self, field, hasValue);
   GPBBecomeVisibleToAutocreator(self);
 }
@@ -671,9 +686,10 @@ void GPBSetInt64IvarWithFieldInternal(GPBMessage *self,
   int64_t *typePtr = (int64_t *)&storage[field->description_->offset];
   *typePtr = value;
   // proto2: any value counts as having been set; proto3, it
-  // has to be a non zero value.
-  BOOL hasValue =
-    (syntax == GPBFileSyntaxProto2) || (value != (int64_t)0);
+  // has to be a non zero value or be in a oneof.
+  BOOL hasValue = ((syntax == GPBFileSyntaxProto2)
+                   || (value != (int64_t)0)
+                   || (field->containingOneof_ != NULL));
   GPBSetHasIvarField(self, field, hasValue);
   GPBBecomeVisibleToAutocreator(self);
 }
@@ -720,9 +736,10 @@ void GPBSetUInt64IvarWithFieldInternal(GPBMessage *self,
   uint64_t *typePtr = (uint64_t *)&storage[field->description_->offset];
   *typePtr = value;
   // proto2: any value counts as having been set; proto3, it
-  // has to be a non zero value.
-  BOOL hasValue =
-    (syntax == GPBFileSyntaxProto2) || (value != (uint64_t)0);
+  // has to be a non zero value or be in a oneof.
+  BOOL hasValue = ((syntax == GPBFileSyntaxProto2)
+                   || (value != (uint64_t)0)
+                   || (field->containingOneof_ != NULL));
   GPBSetHasIvarField(self, field, hasValue);
   GPBBecomeVisibleToAutocreator(self);
 }
@@ -769,9 +786,10 @@ void GPBSetFloatIvarWithFieldInternal(GPBMessage *self,
   float *typePtr = (float *)&storage[field->description_->offset];
   *typePtr = value;
   // proto2: any value counts as having been set; proto3, it
-  // has to be a non zero value.
-  BOOL hasValue =
-    (syntax == GPBFileSyntaxProto2) || (value != (float)0);
+  // has to be a non zero value or be in a oneof.
+  BOOL hasValue = ((syntax == GPBFileSyntaxProto2)
+                   || (value != (float)0)
+                   || (field->containingOneof_ != NULL));
   GPBSetHasIvarField(self, field, hasValue);
   GPBBecomeVisibleToAutocreator(self);
 }
@@ -818,9 +836,10 @@ void GPBSetDoubleIvarWithFieldInternal(GPBMessage *self,
   double *typePtr = (double *)&storage[field->description_->offset];
   *typePtr = value;
   // proto2: any value counts as having been set; proto3, it
-  // has to be a non zero value.
-  BOOL hasValue =
-    (syntax == GPBFileSyntaxProto2) || (value != (double)0);
+  // has to be a non zero value or be in a oneof.
+  BOOL hasValue = ((syntax == GPBFileSyntaxProto2)
+                   || (value != (double)0)
+                   || (field->containingOneof_ != NULL));
   GPBSetHasIvarField(self, field, hasValue);
   GPBBecomeVisibleToAutocreator(self);
 }
@@ -1052,7 +1071,15 @@ static void AppendStringEscaped(NSString *toPrint, NSMutableString *destStr) {
       case '\'': [destStr appendString:@"\\\'"]; break;
       case '\\': [destStr appendString:@"\\\\"]; break;
       default:
-        [destStr appendFormat:@"%C", aChar];
+        // This differs slightly from the C++ code in that the C++ doesn't
+        // generate UTF8; it looks at the string in UTF8, but escapes every
+        // byte > 0x7E.
+        if (aChar < 0x20) {
+          [destStr appendFormat:@"\\%d%d%d",
+                                (aChar / 64), ((aChar % 64) / 8), (aChar % 8)];
+        } else {
+          [destStr appendFormat:@"%C", aChar];
+        }
         break;
     }
   }

objectivec/GPBWellKnownTypes.h

@@ -46,18 +46,54 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-// Extension to GPBTimestamp to work with standard Foundation time/date types.
+/**
+ * Category for GPBTimestamp to work with standard Foundation time/date types.
+ **/
 @interface GPBTimestamp (GBPWellKnownTypes)
+
+/** The NSDate representation of this GPBTimestamp. */
 @property(nonatomic, readwrite, strong) NSDate *date;
+
+/** The NSTimeInterval representation of this GPBTimestamp. */
 @property(nonatomic, readwrite) NSTimeInterval timeIntervalSince1970;
+
+/**
+ * Initializes a GPBTimestamp with the given NSDate.
+ *
+ * @param date The date to configure the GPBTimestamp with.
+ *
+ * @return A newly initialized GPBTimestamp.
+ **/
 - (instancetype)initWithDate:(NSDate *)date;
+
+/**
+ * Initializes a GPBTimestamp with the given NSTimeInterval.
+ *
+ * @param timeIntervalSince1970 Time interval to configure the GPBTimestamp with.
+ *
+ * @return A newly initialized GPBTimestamp.
+ **/
 - (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970;
+
 @end
 
-// Extension to GPBDuration to work with standard Foundation time type.
+/**
+ * Category for GPBDuration to work with standard Foundation time type.
+ **/
 @interface GPBDuration (GBPWellKnownTypes)
+
+/** The NSTimeInterval representation of this GPBTimestamp. */
 @property(nonatomic, readwrite) NSTimeInterval timeIntervalSince1970;
+
+/**
+ * Initializes a GPBDuration with the given NSTimeInterval.
+ *
+ * @param timeIntervalSince1970 Time interval to configure the GPBDuration with.
+ *
+ * @return A newly initialized GPBTimestamp.
+ **/
 - (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970;
+
 @end
 
 NS_ASSUME_NONNULL_END

objectivec/Tests/GPBCodedOuputStreamTests.m

@@ -193,6 +193,32 @@
   }
 }
 
+- (void)assertWriteStringNoTag:(NSData*)data
+                         value:(NSString *)value
+                       context:(NSString *)contextMessage {
+  NSOutputStream* rawOutput = [NSOutputStream outputStreamToMemory];
+  GPBCodedOutputStream* output =
+      [GPBCodedOutputStream streamWithOutputStream:rawOutput];
+  [output writeStringNoTag:value];
+  [output flush];
+
+  NSData* actual =
+      [rawOutput propertyForKey:NSStreamDataWrittenToMemoryStreamKey];
+  XCTAssertEqualObjects(data, actual, @"%@", contextMessage);
+
+  // Try different block sizes.
+  for (int blockSize = 1; blockSize <= 16; blockSize *= 2) {
+    rawOutput = [NSOutputStream outputStreamToMemory];
+    output = [GPBCodedOutputStream streamWithOutputStream:rawOutput
+                                               bufferSize:blockSize];
+    [output writeStringNoTag:value];
+    [output flush];
+
+    actual = [rawOutput propertyForKey:NSStreamDataWrittenToMemoryStreamKey];
+    XCTAssertEqualObjects(data, actual, @"%@", contextMessage);
+  }
+}
+
 - (void)testWriteVarint1 {
   [self assertWriteVarint:bytes(0x00) value:0];
 }
@@ -337,4 +363,64 @@
   XCTAssertEqualObjects(rawBytes, goldenData);
 }
 
+- (void)testCFStringGetCStringPtrAndStringsWithNullChars {
+  // This test exists to verify that CFStrings with embedded NULLs still expose
+  // their raw buffer if they are backed by UTF8 storage. If this fails, the
+  // quick/direct access paths in GPBCodedOutputStream that depend on
+  // CFStringGetCStringPtr need to be re-evalutated (maybe just removed).
+  // And yes, we do get NULLs in strings from some servers.
+
+  char zeroTest[] = "\0Test\0String";
+  // Note: there is a \0 at the end of this since it is a c-string.
+  NSString *asNSString = [[NSString alloc] initWithBytes:zeroTest
+                                                  length:sizeof(zeroTest)
+                                                encoding:NSUTF8StringEncoding];
+  const char *cString =
+      CFStringGetCStringPtr((CFStringRef)asNSString, kCFStringEncodingUTF8);
+  XCTAssertTrue(cString != NULL);
+  // Again, if the above assert fails, then it means NSString no longer exposes
+  // the raw utf8 storage of a string created from utf8 input, so the code using
+  // CFStringGetCStringPtr in GPBCodedOutputStream will still work (it will take
+  // a different code path); but the optimizations for when
+  // CFStringGetCStringPtr does work could possibly go away.
+
+  XCTAssertEqual(sizeof(zeroTest),
+                 [asNSString lengthOfBytesUsingEncoding:NSUTF8StringEncoding]);
+  XCTAssertTrue(0 == memcmp(cString, zeroTest, sizeof(zeroTest)));
+  [asNSString release];
+}
+
+- (void)testWriteStringsWithZeroChar {
+  // Unicode allows `\0` as a character, and NSString is a class cluster, so
+  // there are a few different classes that could end up beind a given string.
+  // Historically, we've seen differences based on constant strings in code and
+  // strings built via the NSString apis. So this round trips them to ensure
+  // they are acting as expected.
+
+  NSArray<NSString *> *strs = @[
+    @"\0at start",
+    @"in\0middle",
+    @"at end\0",
+  ];
+  int i = 0;
+  for (NSString *str in strs) {
+    NSData *asUTF8 = [str dataUsingEncoding:NSUTF8StringEncoding];
+    NSMutableData *expected = [NSMutableData data];
+    uint8_t lengthByte = (uint8_t)asUTF8.length;
+    [expected appendBytes:&lengthByte length:1];
+    [expected appendData:asUTF8];
+
+    NSString *context = [NSString stringWithFormat:@"Loop %d - Literal", i];
+    [self assertWriteStringNoTag:expected value:str context:context];
+
+    // Force a new string to be built which gets a different class from the
+    // NSString class cluster than the literal did.
+    NSString *str2 = [NSString stringWithFormat:@"%@", str];
+    context = [NSString stringWithFormat:@"Loop %d - Built", i];
+    [self assertWriteStringNoTag:expected value:str2 context:context];
+
+    ++i;
+  }
+}
+
 @end

objectivec/Tests/GPBMessageTests+Runtime.m

@@ -1972,6 +1972,254 @@
   [msg release];
 }
 
+- (void)testProto2OneofSetToDefault {
+
+  // proto3 doesn't normally write out zero (default) fields, but if they are
+  // in a oneof it does.  proto2 doesn't have this special behavior, but we
+  // still confirm setting to the explicit default does set the case to be
+  // sure the runtime is working correctly.
+
+  NSString *oneofStringDefault = @"string";
+  NSData *oneofBytesDefault = [@"data" dataUsingEncoding:NSUTF8StringEncoding];
+
+  Message2 *msg = [[Message2 alloc] init];
+
+  uint32_t values[] = {
+    Message2_O_OneOfCase_OneofInt32,
+    Message2_O_OneOfCase_OneofInt64,
+    Message2_O_OneOfCase_OneofUint32,
+    Message2_O_OneOfCase_OneofUint64,
+    Message2_O_OneOfCase_OneofSint32,
+    Message2_O_OneOfCase_OneofSint64,
+    Message2_O_OneOfCase_OneofFixed32,
+    Message2_O_OneOfCase_OneofFixed64,
+    Message2_O_OneOfCase_OneofSfixed32,
+    Message2_O_OneOfCase_OneofSfixed64,
+    Message2_O_OneOfCase_OneofFloat,
+    Message2_O_OneOfCase_OneofDouble,
+    Message2_O_OneOfCase_OneofBool,
+    Message2_O_OneOfCase_OneofString,
+    Message2_O_OneOfCase_OneofBytes,
+    // Skip group
+    // Skip message
+    Message2_O_OneOfCase_OneofEnum,
+  };
+
+  for (size_t i = 0; i < GPBARRAYSIZE(values); ++i) {
+    switch (values[i]) {
+      case Message3_O_OneOfCase_OneofInt32:
+        msg.oneofInt32 = 100;
+        break;
+      case Message3_O_OneOfCase_OneofInt64:
+        msg.oneofInt64 = 101;
+        break;
+      case Message3_O_OneOfCase_OneofUint32:
+        msg.oneofUint32 = 102;
+        break;
+      case Message3_O_OneOfCase_OneofUint64:
+        msg.oneofUint64 = 103;
+        break;
+      case Message3_O_OneOfCase_OneofSint32:
+        msg.oneofSint32 = 104;
+        break;
+      case Message3_O_OneOfCase_OneofSint64:
+        msg.oneofSint64 = 105;
+        break;
+      case Message3_O_OneOfCase_OneofFixed32:
+        msg.oneofFixed32 = 106;
+        break;
+      case Message3_O_OneOfCase_OneofFixed64:
+        msg.oneofFixed64 = 107;
+        break;
+      case Message3_O_OneOfCase_OneofSfixed32:
+        msg.oneofSfixed32 = 108;
+        break;
+      case Message3_O_OneOfCase_OneofSfixed64:
+        msg.oneofSfixed64 = 109;
+        break;
+      case Message3_O_OneOfCase_OneofFloat:
+        msg.oneofFloat = 110.0f;
+        break;
+      case Message3_O_OneOfCase_OneofDouble:
+        msg.oneofDouble = 111.0;
+        break;
+      case Message3_O_OneOfCase_OneofBool:
+        msg.oneofBool = YES;
+        break;
+      case Message3_O_OneOfCase_OneofString:
+        msg.oneofString = oneofStringDefault;
+        break;
+      case Message3_O_OneOfCase_OneofBytes:
+        msg.oneofBytes = oneofBytesDefault;
+        break;
+      case Message3_O_OneOfCase_OneofEnum:
+        msg.oneofEnum = Message3_Enum_Baz;
+        break;
+      default:
+        XCTFail(@"shouldn't happen, loop: %zd, value: %d", i, values[i]);
+        break;
+    }
+
+    // Should be set to the correct case.
+    XCTAssertEqual(msg.oOneOfCase, values[i], "Loop: %zd", i);
+
+    // Confirm everything is back as the defaults.
+    XCTAssertEqual(msg.oneofInt32, 100, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofInt64, 101, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofUint32, 102U, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofUint64, 103U, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofSint32, 104, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofSint64, 105, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofFixed32, 106U, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofFixed64, 107U, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofSfixed32, 108, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofSfixed64, 109, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofFloat, 110.0f, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofDouble, 111.0, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofBool, YES, "Loop: %zd", i);
+    XCTAssertEqualObjects(msg.oneofString, oneofStringDefault, "Loop: %zd", i);
+    XCTAssertEqualObjects(msg.oneofBytes, oneofBytesDefault, "Loop: %zd", i);
+    XCTAssertNotNil(msg.oneofGroup, "Loop: %zd", i);
+    // Skip group
+    // Skip message
+    XCTAssertEqual(msg.oneofEnum, Message2_Enum_Baz, "Loop: %zd", i);
+  }
+
+  // We special case nil on string, data, message, ensure they work as expected.
+  // i.e. - it clears the case.
+  msg.oneofString = nil;
+  XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase);
+  msg.oneofBytes = nil;
+  XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase);
+  msg.oneofMessage = nil;
+  XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase);
+
+  [msg release];
+}
+
+- (void)testProto3OneofSetToZero {
+
+  // Normally setting a proto3 field to the zero value should result in it being
+  // reset/cleared.  But in a oneof, it still gets recored so it can go out
+  // over the wire and the other side can see what was set in the oneof.
+
+  NSString *oneofStringDefault = @"";
+  NSData *oneofBytesDefault = [NSData data];
+
+  Message3 *msg = [[Message3 alloc] init];
+
+  uint32_t values[] = {
+    Message3_O_OneOfCase_OneofInt32,
+    Message3_O_OneOfCase_OneofInt64,
+    Message3_O_OneOfCase_OneofUint32,
+    Message3_O_OneOfCase_OneofUint64,
+    Message3_O_OneOfCase_OneofSint32,
+    Message3_O_OneOfCase_OneofSint64,
+    Message3_O_OneOfCase_OneofFixed32,
+    Message3_O_OneOfCase_OneofFixed64,
+    Message3_O_OneOfCase_OneofSfixed32,
+    Message3_O_OneOfCase_OneofSfixed64,
+    Message3_O_OneOfCase_OneofFloat,
+    Message3_O_OneOfCase_OneofDouble,
+    Message3_O_OneOfCase_OneofBool,
+    Message3_O_OneOfCase_OneofString,
+    Message3_O_OneOfCase_OneofBytes,
+    Message3_O_OneOfCase_OneofMessage,
+    Message3_O_OneOfCase_OneofEnum,
+  };
+
+  for (size_t i = 0; i < GPBARRAYSIZE(values); ++i) {
+    switch (values[i]) {
+      case Message3_O_OneOfCase_OneofInt32:
+        msg.oneofInt32 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofInt64:
+        msg.oneofInt64 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofUint32:
+        msg.oneofUint32 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofUint64:
+        msg.oneofUint64 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofSint32:
+        msg.oneofSint32 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofSint64:
+        msg.oneofSint64 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofFixed32:
+        msg.oneofFixed32 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofFixed64:
+        msg.oneofFixed64 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofSfixed32:
+        msg.oneofSfixed32 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofSfixed64:
+        msg.oneofSfixed64 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofFloat:
+        msg.oneofFloat = 0.0f;
+        break;
+      case Message3_O_OneOfCase_OneofDouble:
+        msg.oneofDouble = 0.0;
+        break;
+      case Message3_O_OneOfCase_OneofBool:
+        msg.oneofBool = NO;
+        break;
+      case Message3_O_OneOfCase_OneofString:
+        msg.oneofString = oneofStringDefault;
+        break;
+      case Message3_O_OneOfCase_OneofBytes:
+        msg.oneofBytes = oneofBytesDefault;
+        break;
+      case Message3_O_OneOfCase_OneofMessage:
+        msg.oneofMessage.optionalInt32 = 0;
+        break;
+      case Message3_O_OneOfCase_OneofEnum:
+        msg.oneofEnum = Message3_Enum_Foo;
+        break;
+      default:
+        XCTFail(@"shouldn't happen, loop: %zd, value: %d", i, values[i]);
+        break;
+    }
+
+    // Should be set to the correct case.
+    XCTAssertEqual(msg.oOneOfCase, values[i], "Loop: %zd", i);
+
+    // Confirm everything is still zeros.
+    XCTAssertEqual(msg.oneofInt32, 0, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofInt64, 0, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofUint32, 0U, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofUint64, 0U, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofSint32, 0, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofSint64, 0, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofFixed32, 0U, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofFixed64, 0U, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofSfixed32, 0, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofSfixed64, 0, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofFloat, 0.0f, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofDouble, 0.0, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofBool, NO, "Loop: %zd", i);
+    XCTAssertEqualObjects(msg.oneofString, oneofStringDefault, "Loop: %zd", i);
+    XCTAssertEqualObjects(msg.oneofBytes, oneofBytesDefault, "Loop: %zd", i);
+    XCTAssertNotNil(msg.oneofMessage, "Loop: %zd", i);
+    XCTAssertEqual(msg.oneofEnum, Message3_Enum_Foo, "Loop: %zd", i);
+  }
+
+  // We special case nil on string, data, message, ensure they work as expected.
+  msg.oneofString = nil;
+  XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase);
+  msg.oneofBytes = nil;
+  XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase);
+  msg.oneofMessage = nil;
+  XCTAssertEqual(msg.oOneOfCase, Message3_O_OneOfCase_GPBUnsetOneOfCase);
+
+  [msg release];
+}
+
 - (void)testCopyingMakesUniqueObjects {
   const int repeatCount = 5;
   TestAllTypes *msg1 = [TestAllTypes message];

objectivec/Tests/unittest_objc.proto

@@ -34,6 +34,15 @@ import "google/protobuf/unittest.proto";
 
 package protobuf_unittest;
 
+// Used to check that Headerdocs and appledoc work correctly. If these comments
+// are not handled correctly, Xcode will fail to build the tests.
+message TestGeneratedComments {
+  // This is a string that could contain stuff like
+  // mime types as image/* or */plain. Maybe twitter usernames
+  // like @protobuf, @google or @something.
+  optional string string_field = 1;
+}
+
 // Using the messages in unittest.proto, setup for recursive cases for testing
 // extensions at various depths.
 extend TestAllExtensions {

objectivec/google/protobuf/Any.pbobjc.h

@@ -28,14 +28,16 @@ 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.
+/**
+ * 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
 @end
 
@@ -46,101 +48,105 @@ typedef GPB_ENUM(GPBAny_FieldNumber) {
   GPBAny_FieldNumber_Value = 2,
 };
 
-/// `Any` contains an arbitrary serialized protocol buffer message along with a
-/// URL that describes the type of the serialized message.
-///
-/// Protobuf library provides support to pack/unpack Any values in the form
-/// of utility functions or additional generated methods of the Any type.
-///
-/// Example 1: Pack and unpack a message in C++.
-///
-///     Foo foo = ...;
-///     Any any;
-///     any.PackFrom(foo);
-///     ...
-///     if (any.UnpackTo(&foo)) {
-///       ...
-///     }
-///
-/// Example 2: Pack and unpack a message in Java.
-///
-///     Foo foo = ...;
-///     Any any = Any.pack(foo);
-///     ...
-///     if (any.is(Foo.class)) {
-///       foo = any.unpack(Foo.class);
-///     }
-///
-///  Example 3: Pack and unpack a message in Python.
-///
-///     foo = Foo(...)
-///     any = Any()
-///     any.Pack(foo)
-///     ...
-///     if any.Is(Foo.DESCRIPTOR):
-///       any.Unpack(foo)
-///       ...
-///
-/// The pack methods provided by protobuf library will by default use
-/// 'type.googleapis.com/full.type.name' as the type URL and the unpack
-/// methods only use the fully qualified type name after the last '/'
-/// in the type URL, for example "foo.bar.com/x/y.z" will yield type
-/// name "y.z".
-///
-///
-/// 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 protocol buffer message along with a
+ * URL that describes the type of the serialized message.
+ *
+ * Protobuf library provides support to pack/unpack Any values in the form
+ * of utility functions or additional generated methods of the Any type.
+ *
+ * Example 1: Pack and unpack a message in C++.
+ *
+ *     Foo foo = ...;
+ *     Any any;
+ *     any.PackFrom(foo);
+ *     ...
+ *     if (any.UnpackTo(&foo)) {
+ *       ...
+ *     }
+ *
+ * Example 2: Pack and unpack a message in Java.
+ *
+ *     Foo foo = ...;
+ *     Any any = Any.pack(foo);
+ *     ...
+ *     if (any.is(Foo.class)) {
+ *       foo = any.unpack(Foo.class);
+ *     }
+ *
+ *  Example 3: Pack and unpack a message in Python.
+ *
+ *     foo = Foo(...)
+ *     any = Any()
+ *     any.Pack(foo)
+ *     ...
+ *     if any.Is(Foo.DESCRIPTOR):
+ *       any.Unpack(foo)
+ *       ...
+ *
+ * The pack methods provided by protobuf library will by default use
+ * 'type.googleapis.com/full.type.name' as the type URL and the unpack
+ * methods only use the fully qualified type name after the last '/'
+ * in the type URL, for example "foo.bar.com/x/y.z" will yield type
+ * name "y.z".
+ *
+ *
+ * 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 protocol buffer message.
-///
-/// For URLs which use the scheme `http`, `https`, or no scheme, the
-/// following restrictions and interpretations apply:
-///
-/// * If no scheme 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`).
-///   The name should be in a canonical form (e.g., leading "." is
-///   not accepted).
-/// * 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.)
-///
-/// Schemes other than `http`, `https` (or the empty scheme) might be
-/// used with implementation specific semantics.
+/**
+ * A URL/resource name whose content describes the type of the
+ * serialized protocol buffer message.
+ *
+ * For URLs which use the scheme `http`, `https`, or no scheme, the
+ * following restrictions and interpretations apply:
+ *
+ * * If no scheme 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`).
+ *   The name should be in a canonical form (e.g., leading "." is
+ *   not accepted).
+ * * 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.)
+ *
+ * Schemes other than `http`, `https` (or the empty scheme) might be
+ * used with implementation specific semantics.
+ **/
 @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL;
 
-/// Must be a valid serialized protocol buffer of the above specified type.
+/** Must be a valid serialized protocol buffer of the above specified type. */
 @property(nonatomic, readwrite, copy, null_resettable) NSData *value;
 
 @end

objectivec/google/protobuf/Api.pbobjc.h

@@ -34,14 +34,16 @@ 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.
+/**
+ * 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
 @end
 
@@ -57,67 +59,79 @@ 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.
+/** 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.
+/** 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.
+/**
+ * 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.
+/** 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.
+/** 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.
+/**
+ * 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.
+/**
+ * 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
@@ -132,40 +146,46 @@ 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.
+/** 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.
+/**
+ * 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.
+/**
+ * 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
@@ -175,90 +195,94 @@ 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

@@ -28,14 +28,16 @@ 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.
+/**
+ * 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
 @end
 
@@ -46,58 +48,64 @@ 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

@@ -28,28 +28,32 @@ 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.
+/**
+ * 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
 @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

@@ -28,14 +28,16 @@ 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.
+/**
+ * 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
 @end
 
@@ -45,212 +47,214 @@ 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 apply 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.
-///
-/// If a repeated field is specified for an update operation, the existing
-/// repeated values in the target resource will be overwritten by the new values.
-/// Note that a repeated field is only allowed in the last position of a field
-/// mask.
-///
-/// If a sub-message is specified in the last position of the field mask for an
-/// update operation, then the existing sub-message in the target resource is
-/// overwritten. Given the target message:
-///
-///     f {
-///       b {
-///         d : 1
-///         x : 2
-///       }
-///       c : 1
-///     }
-///
-/// And an update message:
-///
-///     f {
-///       b {
-///         d : 10
-///       }
-///     }
-///
-/// then if the field mask is:
-///
-///  paths: "f.b"
-///
-/// then the result will be:
-///
-///     f {
-///       b {
-///         d : 10
-///       }
-///       c : 1
-///     }
-///
-/// However, if the update mask was:
-///
-///  paths: "f.b.d"
-///
-/// then the result would be:
-///
-///     f {
-///       b {
-///         d : 10
-///         x : 2
-///       }
-///       c : 1
-///     }
-///
-/// 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"
-///     }
-///
-/// # Field Masks and Oneof Fields
-///
-/// Field masks treat fields in oneofs just as regular fields. Consider the
-/// following message:
-///
-///     message SampleMessage {
-///       oneof test_oneof {
-///         string name = 4;
-///         SubMessage sub_message = 9;
-///       }
-///     }
-///
-/// The field mask can be:
-///
-///     mask {
-///       paths: "name"
-///     }
-///
-/// Or:
-///
-///     mask {
-///       paths: "sub_message"
-///     }
-///
-/// Note that oneof type names ("test_oneof" in this case) cannot be used in
-/// paths.
+/**
+ * `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 apply 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.
+ *
+ * If a repeated field is specified for an update operation, the existing
+ * repeated values in the target resource will be overwritten by the new values.
+ * Note that a repeated field is only allowed in the last position of a field
+ * mask.
+ *
+ * If a sub-message is specified in the last position of the field mask for an
+ * update operation, then the existing sub-message in the target resource is
+ * overwritten. Given the target message:
+ *
+ *     f {
+ *       b {
+ *         d : 1
+ *         x : 2
+ *       }
+ *       c : 1
+ *     }
+ *
+ * And an update message:
+ *
+ *     f {
+ *       b {
+ *         d : 10
+ *       }
+ *     }
+ *
+ * then if the field mask is:
+ *
+ *  paths: "f.b"
+ *
+ * then the result will be:
+ *
+ *     f {
+ *       b {
+ *         d : 10
+ *       }
+ *       c : 1
+ *     }
+ *
+ * However, if the update mask was:
+ *
+ *  paths: "f.b.d"
+ *
+ * then the result would be:
+ *
+ *     f {
+ *       b {
+ *         d : 10
+ *         x : 2
+ *       }
+ *       c : 1
+ *     }
+ *
+ * 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"
+ *     }
+ *
+ * # Field Masks and Oneof Fields
+ *
+ * Field masks treat fields in oneofs just as regular fields. Consider the
+ * following message:
+ *
+ *     message SampleMessage {
+ *       oneof test_oneof {
+ *         string name = 4;
+ *         SubMessage sub_message = 9;
+ *       }
+ *     }
+ *
+ * The field mask can be:
+ *
+ *     mask {
+ *       paths: "name"
+ *     }
+ *
+ * Or:
+ *
+ *     mask {
+ *       paths: "sub_message"
+ *     }
+ *
+ * Note that oneof type names ("test_oneof" in this case) cannot be used in
+ * paths.
+ **/
 @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.
+/** 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

@@ -28,14 +28,16 @@ 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.
+/**
+ * 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
 @end
 
@@ -45,12 +47,16 @@ 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_context.proto"`.
+/**
+ * The path-qualified name of the .proto file that contained the associated
+ * protobuf element.  For example: `"google/protobuf/source_context.proto"`.
+ **/
 @property(nonatomic, readwrite, copy, null_resettable) NSString *fileName;
 
 @end

objectivec/google/protobuf/Struct.pbobjc.h

@@ -32,35 +32,43 @@ 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.
+  /**
+   * 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.
+/**
+ * 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.
+/**
+ * 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
 @end
 
@@ -70,19 +78,21 @@ 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
 
-/// Unordered map of dynamically typed values.
+/** Unordered 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.
+/** The number of items in @c fields without causing the array to be created. */
 @property(nonatomic, readonly) NSUInteger fields_Count;
 
 @end
@@ -108,46 +118,54 @@ 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.
+/**
+ * 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.
+/**
+ * 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'.
+/**
+ * Clears whatever value was set for the oneof 'kind'.
+ **/
 void GPBValue_ClearKindOneOfCase(GPBValue *message);
 
 #pragma mark - GPBListValue
@@ -156,14 +174,16 @@ 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.
+/** 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

@@ -28,14 +28,16 @@ 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.
+/**
+ * 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
 @end
 
@@ -46,70 +48,76 @@ 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

@@ -34,134 +34,148 @@ 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.
+  /**
+   * 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.
+/**
+ * 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.
+  /**
+   * 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.
+/**
+ * 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.
+  /**
+   * 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.
+/**
+ * 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.
+/**
+ * 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
 @end
 
@@ -176,43 +190,49 @@ 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.
+/** 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.
+/** 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.
+/** The number of items in @c optionsArray without causing the array to be created. */
 @property(nonatomic, readonly) NSUInteger optionsArray_Count;
 
-/// The source context.
+/** The source context. */
 @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext;
-/// Test to see if @c sourceContext has been set.
+/** 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.
+/**
+ * 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.
+/**
+ * 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
@@ -230,59 +250,73 @@ 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.
+/** 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.
+/**
+ * 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.
+/**
+ * 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.
+/**
+ * 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.
+/**
+ * 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
@@ -295,38 +329,44 @@ 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.
+/** 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.
+/** The number of items in @c optionsArray without causing the array to be created. */
 @property(nonatomic, readonly) NSUInteger optionsArray_Count;
 
-/// The source context.
+/** The source context. */
 @property(nonatomic, readwrite, strong, null_resettable) GPBSourceContext *sourceContext;
-/// Test to see if @c sourceContext has been set.
+/** 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.
+/**
+ * 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.
+/**
+ * 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
@@ -337,18 +377,20 @@ 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.
+/** The number of items in @c optionsArray without causing the array to be created. */
 @property(nonatomic, readonly) NSUInteger optionsArray_Count;
 
 @end
@@ -360,16 +402,18 @@ 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"`.
+/** 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.
+/** Test to see if @c value has been set. */
 @property(nonatomic, readwrite) BOOL hasValue;
 
 @end

objectivec/google/protobuf/Wrappers.pbobjc.h

@@ -28,14 +28,16 @@ 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.
+/**
+ * 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
 @end
 
@@ -45,12 +47,14 @@ 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
@@ -61,12 +65,14 @@ 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
@@ -77,12 +83,14 @@ 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
@@ -93,12 +101,14 @@ 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
@@ -109,12 +119,14 @@ 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
@@ -125,12 +137,14 @@ 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
@@ -141,12 +155,14 @@ 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
@@ -157,12 +173,14 @@ 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
@@ -173,12 +191,14 @@ 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

@@ -62,7 +62,7 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) {
   string enum_comments;
   SourceLocation location;
   if (descriptor_->GetSourceLocation(&location)) {
-    enum_comments = BuildCommentsString(location);
+    enum_comments = BuildCommentsString(location, true);
   } else {
     enum_comments = "";
   }
@@ -81,16 +81,18 @@ 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"
+      "/**\n"
+      " * 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"
+      " **/\n"
       "$name$_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue,\n",
       "name", name_);
   }
   for (int i = 0; i < all_values_.size(); i++) {
     SourceLocation location;
     if (all_values_[i]->GetSourceLocation(&location)) {
-      string comments = BuildCommentsString(location).c_str();
+      string comments = BuildCommentsString(location, true).c_str();
       if (comments.length() > 0) {
         if (i > 0) {
           printer->Print("\n");
@@ -111,8 +113,10 @@ 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"
+      "/**\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"
+      " **/\n"
       "BOOL $name$_IsValidValue(int32_t value);\n"
       "\n",
       "name", name_);

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

@@ -83,12 +83,16 @@ 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"
+      "/**\n"
+      " * 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"
+      " **/\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"
+      "/**\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"
+      " **/\n"
       "void Set$owning_message_class$_$capitalized_name$_RawValue($owning_message_class$ *message, int32_t value);\n"
       "\n");
 }

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

@@ -63,7 +63,7 @@ void ExtensionGenerator::GenerateMembersHeader(io::Printer* printer) {
   vars["method_name"] = method_name_;
   SourceLocation location;
   if (descriptor_->GetSourceLocation(&location)) {
-    vars["comments"] = BuildCommentsString(location);
+    vars["comments"] = BuildCommentsString(location, true);
   } else {
     vars["comments"] = "";
   }

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

@@ -64,7 +64,7 @@ void SetCommonFieldVariables(const FieldDescriptor* descriptor,
 
   SourceLocation location;
   if (descriptor->GetSourceLocation(&location)) {
-    (*variables)["comments"] = BuildCommentsString(location);
+    (*variables)["comments"] = BuildCommentsString(location, true);
   } else {
     (*variables)["comments"] = "\n";
   }
@@ -335,7 +335,7 @@ void ObjCObjFieldGenerator::GeneratePropertyDeclaration(
   if (WantsHasProperty()) {
     printer->Print(
         variables_,
-        "/// Test to see if @c $name$ has been set.\n"
+        "/** Test to see if @c $name$ has been set. */\n"
         "@property(nonatomic, readwrite) BOOL has$capitalized_name$$deprecated_attribute$;\n");
   }
   if (IsInitName(variables_.find("name")->second)) {
@@ -387,7 +387,7 @@ void RepeatedFieldGenerator::GeneratePropertyDeclaration(
       "$comments$"
       "$array_comment$"
       "@property(nonatomic, readwrite, strong, null_resettable) $array_property_type$ *$name$$storage_attribute$$deprecated_attribute$;\n"
-      "/// The number of items in @c $name$ without causing the array to be created.\n"
+      "/** The number of items in @c $name$ without causing the array to be created. */\n"
       "@property(nonatomic, readonly) NSUInteger $name$_Count$deprecated_attribute$;\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

@@ -357,14 +357,16 @@ 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"
+      "/**\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"
+      " **/\n"
       "@interface $root_class_name$ : GPBRootObject\n"
       "@end\n"
       "\n",

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

@@ -830,7 +830,8 @@ string BuildFlagsString(const vector<string>& strings) {
   return string;
 }
 
-string BuildCommentsString(const SourceLocation& location) {
+string BuildCommentsString(const SourceLocation& location,
+                           bool prefer_single_line) {
   const string& comments = location.leading_comments.empty()
                                ? location.trailing_comments
                                : location.leading_comments;
@@ -839,15 +840,45 @@ string BuildCommentsString(const SourceLocation& location) {
   while (!lines.empty() && lines.back().empty()) {
     lines.pop_back();
   }
-  string prefix("///");
-  string suffix("\n");
+  // If there are no comments, just return an empty string.
+  if (lines.size() == 0) {
+    return "";
+  }
+
+  string prefix;
+  string suffix;
   string final_comments;
-  for (int i = 0; i < lines.size(); i++) {
-    // HeaderDoc uses '\' and '@' for markers; escape them.
-    const string line = StringReplace(lines[i], "\\", "\\\\", true);
-    final_comments +=
-        prefix + StringReplace(line, "@", "\\@", true) + suffix;
+  string epilogue;
+
+  bool add_leading_space = false;
+
+  if (prefer_single_line && lines.size() == 1) {
+    prefix = "/** ";
+    suffix = " */\n";
+  } else {
+    prefix = "* ";
+    suffix = "\n";
+    final_comments += "/**\n";
+    epilogue = " **/\n";
+    add_leading_space = true;
   }
+
+  for (int i = 0; i < lines.size(); i++) {
+    string line = StripPrefixString(lines[i], " ");
+    // HeaderDoc and appledoc use '\' and '@' for markers; escape them.
+    line = StringReplace(line, "\\", "\\\\", true);
+    line = StringReplace(line, "@", "\\@", true);
+    // Decouple / from * to not have inline comments inside comments.
+    line = StringReplace(line, "/*", "/\\*", true);
+    line = StringReplace(line, "*/", "*\\/", true);
+    line = prefix + line;
+    StripWhitespace(&line);
+    // If not a one line, need to add the first space before *, as
+    // StripWhitespace would have removed it.
+    line = (add_leading_space ? " " : "") + line;
+    final_comments += line + suffix;
+  }
+  final_comments += epilogue;
   return final_comments;
 }
 

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

@@ -172,8 +172,10 @@ bool HasNonZeroDefaultValue(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);
+// Builds HeaderDoc/appledoc style comments out of the comments in the .proto
+// file.
+string BuildCommentsString(const SourceLocation& location,
+                           bool prefer_single_line);
 
 // The name the commonly used by the library when built as a framework.
 // This lines up to the name used in the CocoaPod.

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

@@ -331,7 +331,7 @@ void MessageGenerator::GenerateMessageHeader(io::Printer* printer) {
   string message_comments;
   SourceLocation location;
   if (descriptor_->GetSourceLocation(&location)) {
-    message_comments = BuildCommentsString(location);
+    message_comments = BuildCommentsString(location, false);
   } else {
     message_comments = "";
   }

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

@@ -53,7 +53,7 @@ OneofGenerator::OneofGenerator(const OneofDescriptor* descriptor)
   string comments;
   SourceLocation location;
   if (descriptor_->GetSourceLocation(&location)) {
-    comments = BuildCommentsString(location);
+    comments = BuildCommentsString(location, true);
   } else {
     comments = "";
   }
@@ -104,7 +104,9 @@ void OneofGenerator::GeneratePublicCasePropertyDeclaration(
 void OneofGenerator::GenerateClearFunctionDeclaration(io::Printer* printer) {
   printer->Print(
       variables_,
-      "/// Clears whatever value was set for the oneof '$name$'.\n"
+      "/**\n"
+      " * Clears whatever value was set for the oneof '$name$'.\n"
+      " **/\n"
       "void $owning_message_class$_Clear$capitalized_name$OneOfCase($owning_message_class$ *message);\n");
 }