Merge pull request #1975 from pherl/cp

Cherry pick objc changes into 3.0.0-GA branch

conformance/failure_list_objc.txt

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

objectivec/GPBBootstrap.h

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

objectivec/GPBCodedInputStream.h

@@ -37,125 +37,194 @@ NS_ASSUME_NONNULL_BEGIN
 
 CF_EXTERN_C_BEGIN
 
-/// GPBCodedInputStream exception name. Exceptions raised from
-/// GPBCodedInputStream contain an underlying error in the userInfo dictionary
-/// under the GPBCodedInputStreamUnderlyingErrorKey key.
+/**
+ * @c GPBCodedInputStream exception name. Exceptions raised from
+ * @c GPBCodedInputStream contain an underlying error in the userInfo dictionary
+ * under the GPBCodedInputStreamUnderlyingErrorKey key.
+ **/
 extern NSString *const GPBCodedInputStreamException;
 
-/// The key under which the underlying NSError from the exception is stored.
+/** The key under which the underlying NSError from the exception is stored. */
 extern NSString *const GPBCodedInputStreamUnderlyingErrorKey;
 
-/// NSError domain used for GPBCodedInputStream errors.
+/** NSError domain used for @c GPBCodedInputStream errors. */
 extern NSString *const GPBCodedInputStreamErrorDomain;
 
-/// Error code for NSError with GPBCodedInputStreamErrorDomain.
+/**
+ * Error code for NSError with @c GPBCodedInputStreamErrorDomain.
+ **/
 typedef NS_ENUM(NSInteger, GPBCodedInputStreamErrorCode) {
-  /// The size does not fit in the remaining bytes to be read.
+  /** The size does not fit in the remaining bytes to be read. */
   GPBCodedInputStreamErrorInvalidSize = -100,
-  /// Attempted to read beyond the subsection limit.
+  /** Attempted to read beyond the subsection limit. */
   GPBCodedInputStreamErrorSubsectionLimitReached = -101,
-  /// The requested subsection limit is invalid.
+  /** The requested subsection limit is invalid. */
   GPBCodedInputStreamErrorInvalidSubsectionLimit = -102,
-  /// Invalid tag read.
+  /** Invalid tag read. */
   GPBCodedInputStreamErrorInvalidTag = -103,
-  /// Invalid UTF-8 character in a string.
+  /** Invalid UTF-8 character in a string. */
   GPBCodedInputStreamErrorInvalidUTF8 = -104,
-  /// Invalid VarInt read.
+  /** Invalid VarInt read. */
   GPBCodedInputStreamErrorInvalidVarInt = -105,
-  /// The maximum recursion depth of messages was exceeded.
+  /** The maximum recursion depth of messages was exceeded. */
   GPBCodedInputStreamErrorRecursionDepthExceeded = -106,
 };
 
 CF_EXTERN_C_END
 
-/// Reads and decodes protocol message fields.
-///
-/// The common uses of protocol buffers shouldn't need to use this class.
-/// @c GPBMessage's provide a @c +parseFromData:error: and @c
-/// +parseFromData:extensionRegistry:error: method that will decode a
-/// message for you.
-///
-/// @note Subclassing of GPBCodedInputStream is NOT supported.
+/**
+ * Reads and decodes protocol message fields.
+ *
+ * The common uses of protocol buffers shouldn't need to use this class.
+ * @c GPBMessage's provide a @c +parseFromData:error: and
+ * @c +parseFromData:extensionRegistry:error: method that will decode a
+ * message for you.
+ *
+ * @note Subclassing of @c GPBCodedInputStream is NOT supported.
+ **/
 @interface GPBCodedInputStream : NSObject
 
-/// Creates a new stream wrapping some data.
+/**
+ * Creates a new stream wrapping some data.
+ *
+ * @param data The data to wrap inside the stream.
+ *
+ * @return A newly instanced GPBCodedInputStream.
+ **/
 + (instancetype)streamWithData:(NSData *)data;
 
-/// Initializes a stream wrapping some data.
+/**
+ * Initializes a stream wrapping some data.
+ *
+ * @param data The data to wrap inside the stream.
+ *
+ * @return A newly initialized GPBCodedInputStream.
+ **/
 - (instancetype)initWithData:(NSData *)data;
 
-/// Attempt to read a field tag, returning zero if we have reached EOF.
-/// Protocol message parsers use this to read tags, since a protocol message
-/// may legally end wherever a tag occurs, and zero is not a valid tag number.
+/**
+ * Attempts to read a field tag, returning zero if we have reached EOF.
+ * Protocol message parsers use this to read tags, since a protocol message
+ * may legally end wherever a tag occurs, and zero is not a valid tag number.
+ *
+ * @return The field tag, or zero if EOF was reached.
+ **/
 - (int32_t)readTag;
 
-/// Read and return a double.
+/**
+ * @return A double read from the stream.
+ **/
 - (double)readDouble;
-/// Read and return a float.
+/**
+ * @return A float read from the stream.
+ **/
 - (float)readFloat;
-/// Read and return a uint64.
+/**
+ * @return A uint64 read from the stream.
+ **/
 - (uint64_t)readUInt64;
-/// Read and return a uint32.
+/**
+ * @return A uint32 read from the stream.
+ **/
 - (uint32_t)readUInt32;
-/// Read and return an int64.
+/**
+ * @return An int64 read from the stream.
+ **/
 - (int64_t)readInt64;
-/// Read and return an int32.
+/**
+ * @return An int32 read from the stream.
+ **/
 - (int32_t)readInt32;
-/// Read and return a fixed64.
+/**
+ * @return A fixed64 read from the stream.
+ **/
 - (uint64_t)readFixed64;
-/// Read and return a fixed32.
+/**
+ * @return A fixed32 read from the stream.
+ **/
 - (uint32_t)readFixed32;
-/// Read and return an enum (int).
+/**
+ * @return An enum read from the stream.
+ **/
 - (int32_t)readEnum;
-/// Read and return a sfixed32.
+/**
+ * @return A sfixed32 read from the stream.
+ **/
 - (int32_t)readSFixed32;
-/// Read and return a sfixed64.
+/**
+ * @return A fixed64 read from the stream.
+ **/
 - (int64_t)readSFixed64;
-/// Read and return a sint32.
+/**
+ * @return A sint32 read from the stream.
+ **/
 - (int32_t)readSInt32;
-/// Read and return a sint64.
+/**
+ * @return A sint64 read from the stream.
+ **/
 - (int64_t)readSInt64;
-/// Read and return a boolean.
+/**
+ * @return A boolean read from the stream.
+ **/
 - (BOOL)readBool;
-/// Read and return a string.
+/**
+ * @return A string read from the stream.
+ **/
 - (NSString *)readString;
-/// Read and return length delimited data.
+/**
+ * @return Data read from the stream.
+ **/
 - (NSData *)readBytes;
 
-/// Read an embedded message field value from the stream.
-///
-/// @param message           The message to set fields on as they are read.
-/// @param extensionRegistry An optional extension registry to use to lookup
-///                          extensions for @c message.
+/**
+ * Read an embedded message field value from the stream.
+ *
+ * @param message           The message to set fields on as they are read.
+ * @param extensionRegistry An optional extension registry to use to lookup
+ *                          extensions for message.
+ **/
 - (void)readMessage:(GPBMessage *)message
   extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
 
-/// Reads and discards a single field, given its tag value.
-///
-/// @param tag The tag number of the field to skip.
-///
-/// @return NO if the tag is an endgroup tag (in which case nothing is skipped),
-///         YES in all other cases.
+/**
+ * Reads and discards a single field, given its tag value.
+ *
+ * @param tag The tag number of the field to skip.
+ *
+ * @return NO if the tag is an endgroup tag (in which case nothing is skipped),
+ *         YES in all other cases.
+ **/
 - (BOOL)skipField:(int32_t)tag;
 
-/// Reads and discards an entire message.  This will read either until EOF
-/// or until an endgroup tag, whichever comes first.
+/**
+ * Reads and discards an entire message. This will read either until EOF or
+ * until an endgroup tag, whichever comes first.
+ **/
 - (void)skipMessage;
 
-/// Check to see if the logical end of the stream has been reached.
-///
-/// This can return NO when there is no more data, but the current parsing
-/// expected more data.
+/**
+ * Check to see if the logical end of the stream has been reached.
+ *
+ * @note This can return NO when there is no more data, but the current parsing
+ *       expected more data.
+ *
+ * @return YES if the logical end of the stream has been reached, NO otherwise.
+ **/
 - (BOOL)isAtEnd;
 
-/// The offset into the stream.
+/**
+ * @return The offset into the stream.
+ **/
 - (size_t)position;
 
-/// Verifies that the last call to @c -readTag returned the given tag value.
-/// This is used to verify that a nested group ended with the correct end tag.
-/// Throws @c NSParseErrorException if value does not match the last tag.
-///
-/// @param expected The tag that was expected.
+/**
+ * Verifies that the last call to -readTag returned the given tag value. This
+ * is used to verify that a nested group ended with the correct end tag.
+ *
+ * @exception NSParseErrorException If the value does not match the last tag.
+ *
+ * @param expected The tag that was expected.
+ **/
 - (void)checkLastTagWas:(int32_t)expected;
 
 @end

objectivec/GPBCodedOutputStream.m

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

objectivec/GPBDescriptor.h

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

objectivec/GPBExtensionRegistry.h

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

objectivec/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/GPBWellKnownTypes.h

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

objectivec/Tests/unittest_objc.proto

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

objectivec/google/protobuf/Empty.pbobjc.h

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