Migrating documentation of the ObjectiveC runtime code to appledoc. (#1867)

Work for #1866 

Migrates all the public class docs over to appledoc format.  While Xcode is fine with blank lines in `///` comments, appledoc (used by cocoadocs) isn't and was leaving a bunch of info off the doc pages.

The generator still needs to be updated to do this also; that will be a follow up CL.

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/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  GPBExtensionDescripto 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/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