Adds support for appledoc in generated code. (#1928)

Convert mapping of proto comments to appledoc format so they show up in Xcode and cocoadocs.

Fixes https://github.com/google/protobuf/issues/1866

objectivec/Tests/unittest_objc.proto

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

objectivec/google/protobuf/Any.pbobjc.h

@@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - GPBAnyRoot
 
-/// Exposes the extension registry for this file.
-///
-/// The base class provides:
-/// @code
-///   + (GPBExtensionRegistry *)extensionRegistry;
-/// @endcode
-/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
-/// this file and all files that it depends on.
+/**
+ * Exposes the extension registry for this file.
+ *
+ * The base class provides:
+ * @code
+ *   + (GPBExtensionRegistry *)extensionRegistry;
+ * @endcode
+ * which is a @c GPBExtensionRegistry that includes all the extensions defined by
+ * this file and all files that it depends on.
+ **/
 @interface GPBAnyRoot : GPBRootObject
 @end
 
@@ -46,101 +48,105 @@ typedef GPB_ENUM(GPBAny_FieldNumber) {
   GPBAny_FieldNumber_Value = 2,
 };
 
-/// `Any` contains an arbitrary serialized protocol buffer message along with a
-/// URL that describes the type of the serialized message.
-///
-/// Protobuf library provides support to pack/unpack Any values in the form
-/// of utility functions or additional generated methods of the Any type.
-///
-/// Example 1: Pack and unpack a message in C++.
-///
-///     Foo foo = ...;
-///     Any any;
-///     any.PackFrom(foo);
-///     ...
-///     if (any.UnpackTo(&foo)) {
-///       ...
-///     }
-///
-/// Example 2: Pack and unpack a message in Java.
-///
-///     Foo foo = ...;
-///     Any any = Any.pack(foo);
-///     ...
-///     if (any.is(Foo.class)) {
-///       foo = any.unpack(Foo.class);
-///     }
-///
-///  Example 3: Pack and unpack a message in Python.
-///
-///     foo = Foo(...)
-///     any = Any()
-///     any.Pack(foo)
-///     ...
-///     if any.Is(Foo.DESCRIPTOR):
-///       any.Unpack(foo)
-///       ...
-///
-/// The pack methods provided by protobuf library will by default use
-/// 'type.googleapis.com/full.type.name' as the type URL and the unpack
-/// methods only use the fully qualified type name after the last '/'
-/// in the type URL, for example "foo.bar.com/x/y.z" will yield type
-/// name "y.z".
-///
-///
-/// JSON
-/// ====
-/// The JSON representation of an `Any` value uses the regular
-/// representation of the deserialized, embedded message, with an
-/// additional field `\@type` which contains the type URL. Example:
-///
-///     package google.profile;
-///     message Person {
-///       string first_name = 1;
-///       string last_name = 2;
-///     }
-///
-///     {
-///       "\@type": "type.googleapis.com/google.profile.Person",
-///       "firstName": <string>,
-///       "lastName": <string>
-///     }
-///
-/// If the embedded message type is well-known and has a custom JSON
-/// representation, that representation will be embedded adding a field
-/// `value` which holds the custom JSON in addition to the `\@type`
-/// field. Example (for message [google.protobuf.Duration][]):
-///
-///     {
-///       "\@type": "type.googleapis.com/google.protobuf.Duration",
-///       "value": "1.212s"
-///     }
+/**
+ * `Any` contains an arbitrary serialized protocol buffer message along with a
+ * URL that describes the type of the serialized message.
+ * 
+ * Protobuf library provides support to pack/unpack Any values in the form
+ * of utility functions or additional generated methods of the Any type.
+ * 
+ * Example 1: Pack and unpack a message in C++.
+ * 
+ *     Foo foo = ...;
+ *     Any any;
+ *     any.PackFrom(foo);
+ *     ...
+ *     if (any.UnpackTo(&foo)) {
+ *       ...
+ *     }
+ * 
+ * Example 2: Pack and unpack a message in Java.
+ * 
+ *     Foo foo = ...;
+ *     Any any = Any.pack(foo);
+ *     ...
+ *     if (any.is(Foo.class)) {
+ *       foo = any.unpack(Foo.class);
+ *     }
+ * 
+ *  Example 3: Pack and unpack a message in Python.
+ * 
+ *     foo = Foo(...)
+ *     any = Any()
+ *     any.Pack(foo)
+ *     ...
+ *     if any.Is(Foo.DESCRIPTOR):
+ *       any.Unpack(foo)
+ *       ...
+ * 
+ * The pack methods provided by protobuf library will by default use
+ * 'type.googleapis.com/full.type.name' as the type URL and the unpack
+ * methods only use the fully qualified type name after the last '/'
+ * in the type URL, for example "foo.bar.com/x/y.z" will yield type
+ * name "y.z".
+ * 
+ * 
+ * JSON
+ * ====
+ * The JSON representation of an `Any` value uses the regular
+ * representation of the deserialized, embedded message, with an
+ * additional field `\@type` which contains the type URL. Example:
+ * 
+ *     package google.profile;
+ *     message Person {
+ *       string first_name = 1;
+ *       string last_name = 2;
+ *     }
+ * 
+ *     {
+ *       "\@type": "type.googleapis.com/google.profile.Person",
+ *       "firstName": <string>,
+ *       "lastName": <string>
+ *     }
+ * 
+ * If the embedded message type is well-known and has a custom JSON
+ * representation, that representation will be embedded adding a field
+ * `value` which holds the custom JSON in addition to the `\@type`
+ * field. Example (for message [google.protobuf.Duration][]):
+ * 
+ *     {
+ *       "\@type": "type.googleapis.com/google.protobuf.Duration",
+ *       "value": "1.212s"
+ *     }
+ **/
 @interface GPBAny : GPBMessage
 
-/// A URL/resource name whose content describes the type of the
-/// serialized protocol buffer message.
-///
-/// For URLs which use the scheme `http`, `https`, or no scheme, the
-/// following restrictions and interpretations apply:
-///
-/// * If no scheme is provided, `https` is assumed.
-/// * The last segment of the URL's path must represent the fully
-///   qualified name of the type (as in `path/google.protobuf.Duration`).
-///   The name should be in a canonical form (e.g., leading "." is
-///   not accepted).
-/// * An HTTP GET on the URL must yield a [google.protobuf.Type][]
-///   value in binary format, or produce an error.
-/// * Applications are allowed to cache lookup results based on the
-///   URL, or have them precompiled into a binary to avoid any
-///   lookup. Therefore, binary compatibility needs to be preserved
-///   on changes to types. (Use versioned type names to manage
-///   breaking changes.)
-///
-/// Schemes other than `http`, `https` (or the empty scheme) might be
-/// used with implementation specific semantics.
+/**
+ * A URL/resource name whose content describes the type of the
+ * serialized protocol buffer message.
+ * 
+ * For URLs which use the scheme `http`, `https`, or no scheme, the
+ * following restrictions and interpretations apply:
+ * 
+ * * If no scheme is provided, `https` is assumed.
+ * * The last segment of the URL's path must represent the fully
+ *   qualified name of the type (as in `path/google.protobuf.Duration`).
+ *   The name should be in a canonical form (e.g., leading "." is
+ *   not accepted).
+ * * An HTTP GET on the URL must yield a [google.protobuf.Type][]
+ *   value in binary format, or produce an error.
+ * * Applications are allowed to cache lookup results based on the
+ *   URL, or have them precompiled into a binary to avoid any
+ *   lookup. Therefore, binary compatibility needs to be preserved
+ *   on changes to types. (Use versioned type names to manage
+ *   breaking changes.)
+ * 
+ * Schemes other than `http`, `https` (or the empty scheme) might be
+ * used with implementation specific semantics.
+ **/
 @property(nonatomic, readwrite, copy, null_resettable) NSString *typeURL;
 
-/// Must be a valid serialized protocol buffer of the above specified type.
+/** Must be a valid serialized protocol buffer of the above specified type. */
 @property(nonatomic, readwrite, copy, null_resettable) NSData *value;
 
 @end

objectivec/google/protobuf/Api.pbobjc.h

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

objectivec/google/protobuf/Duration.pbobjc.h

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

objectivec/google/protobuf/Empty.pbobjc.h

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

objectivec/google/protobuf/FieldMask.pbobjc.h

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

objectivec/google/protobuf/SourceContext.pbobjc.h

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

objectivec/google/protobuf/Struct.pbobjc.h

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

objectivec/google/protobuf/Timestamp.pbobjc.h

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

objectivec/google/protobuf/Type.pbobjc.h

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

objectivec/google/protobuf/Wrappers.pbobjc.h

@@ -28,14 +28,16 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - GPBWrappersRoot
 
-/// Exposes the extension registry for this file.
-///
-/// The base class provides:
-/// @code
-///   + (GPBExtensionRegistry *)extensionRegistry;
-/// @endcode
-/// which is a @c GPBExtensionRegistry that includes all the extensions defined by
-/// this file and all files that it depends on.
+/**
+ * Exposes the extension registry for this file.
+ *
+ * The base class provides:
+ * @code
+ *   + (GPBExtensionRegistry *)extensionRegistry;
+ * @endcode
+ * which is a @c GPBExtensionRegistry that includes all the extensions defined by
+ * this file and all files that it depends on.
+ **/
 @interface GPBWrappersRoot : GPBRootObject
 @end
 
@@ -45,12 +47,14 @@ typedef GPB_ENUM(GPBDoubleValue_FieldNumber) {
   GPBDoubleValue_FieldNumber_Value = 1,
 };
 
-/// Wrapper message for `double`.
-///
-/// The JSON representation for `DoubleValue` is JSON number.
+/**
+ * Wrapper message for `double`.
+ * 
+ * The JSON representation for `DoubleValue` is JSON number.
+ **/
 @interface GPBDoubleValue : GPBMessage
 
-/// The double value.
+/** The double value. */
 @property(nonatomic, readwrite) double value;
 
 @end
@@ -61,12 +65,14 @@ typedef GPB_ENUM(GPBFloatValue_FieldNumber) {
   GPBFloatValue_FieldNumber_Value = 1,
 };
 
-/// Wrapper message for `float`.
-///
-/// The JSON representation for `FloatValue` is JSON number.
+/**
+ * Wrapper message for `float`.
+ * 
+ * The JSON representation for `FloatValue` is JSON number.
+ **/
 @interface GPBFloatValue : GPBMessage
 
-/// The float value.
+/** The float value. */
 @property(nonatomic, readwrite) float value;
 
 @end
@@ -77,12 +83,14 @@ typedef GPB_ENUM(GPBInt64Value_FieldNumber) {
   GPBInt64Value_FieldNumber_Value = 1,
 };
 
-/// Wrapper message for `int64`.
-///
-/// The JSON representation for `Int64Value` is JSON string.
+/**
+ * Wrapper message for `int64`.
+ * 
+ * The JSON representation for `Int64Value` is JSON string.
+ **/
 @interface GPBInt64Value : GPBMessage
 
-/// The int64 value.
+/** The int64 value. */
 @property(nonatomic, readwrite) int64_t value;
 
 @end
@@ -93,12 +101,14 @@ typedef GPB_ENUM(GPBUInt64Value_FieldNumber) {
   GPBUInt64Value_FieldNumber_Value = 1,
 };
 
-/// Wrapper message for `uint64`.
-///
-/// The JSON representation for `UInt64Value` is JSON string.
+/**
+ * Wrapper message for `uint64`.
+ * 
+ * The JSON representation for `UInt64Value` is JSON string.
+ **/
 @interface GPBUInt64Value : GPBMessage
 
-/// The uint64 value.
+/** The uint64 value. */
 @property(nonatomic, readwrite) uint64_t value;
 
 @end
@@ -109,12 +119,14 @@ typedef GPB_ENUM(GPBInt32Value_FieldNumber) {
   GPBInt32Value_FieldNumber_Value = 1,
 };
 
-/// Wrapper message for `int32`.
-///
-/// The JSON representation for `Int32Value` is JSON number.
+/**
+ * Wrapper message for `int32`.
+ * 
+ * The JSON representation for `Int32Value` is JSON number.
+ **/
 @interface GPBInt32Value : GPBMessage
 
-/// The int32 value.
+/** The int32 value. */
 @property(nonatomic, readwrite) int32_t value;
 
 @end
@@ -125,12 +137,14 @@ typedef GPB_ENUM(GPBUInt32Value_FieldNumber) {
   GPBUInt32Value_FieldNumber_Value = 1,
 };
 
-/// Wrapper message for `uint32`.
-///
-/// The JSON representation for `UInt32Value` is JSON number.
+/**
+ * Wrapper message for `uint32`.
+ * 
+ * The JSON representation for `UInt32Value` is JSON number.
+ **/
 @interface GPBUInt32Value : GPBMessage
 
-/// The uint32 value.
+/** The uint32 value. */
 @property(nonatomic, readwrite) uint32_t value;
 
 @end
@@ -141,12 +155,14 @@ typedef GPB_ENUM(GPBBoolValue_FieldNumber) {
   GPBBoolValue_FieldNumber_Value = 1,
 };
 
-/// Wrapper message for `bool`.
-///
-/// The JSON representation for `BoolValue` is JSON `true` and `false`.
+/**
+ * Wrapper message for `bool`.
+ * 
+ * The JSON representation for `BoolValue` is JSON `true` and `false`.
+ **/
 @interface GPBBoolValue : GPBMessage
 
-/// The bool value.
+/** The bool value. */
 @property(nonatomic, readwrite) BOOL value;
 
 @end
@@ -157,12 +173,14 @@ typedef GPB_ENUM(GPBStringValue_FieldNumber) {
   GPBStringValue_FieldNumber_Value = 1,
 };
 
-/// Wrapper message for `string`.
-///
-/// The JSON representation for `StringValue` is JSON string.
+/**
+ * Wrapper message for `string`.
+ * 
+ * The JSON representation for `StringValue` is JSON string.
+ **/
 @interface GPBStringValue : GPBMessage
 
-/// The string value.
+/** The string value. */
 @property(nonatomic, readwrite, copy, null_resettable) NSString *value;
 
 @end
@@ -173,12 +191,14 @@ typedef GPB_ENUM(GPBBytesValue_FieldNumber) {
   GPBBytesValue_FieldNumber_Value = 1,
 };
 
-/// Wrapper message for `bytes`.
-///
-/// The JSON representation for `BytesValue` is JSON string.
+/**
+ * Wrapper message for `bytes`.
+ * 
+ * The JSON representation for `BytesValue` is JSON string.
+ **/
 @interface GPBBytesValue : GPBMessage
 
-/// The bytes value.
+/** The bytes value. */
 @property(nonatomic, readwrite, copy, null_resettable) NSData *value;
 
 @end

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -170,8 +170,10 @@ bool HasNonZeroDefaultValue(const FieldDescriptor* field);
 
 string BuildFlagsString(const vector<string>& strings);
 
-// Builds a HeaderDoc style comment out of the comments in the .proto file.
-string BuildCommentsString(const SourceLocation& location);
+// Builds HeaderDoc/appledoc style comments out of the comments in the .proto
+// file.
+string BuildCommentsString(const SourceLocation& location,
+                           bool prefer_single_line);
 
 // The name the commonly used by the library when built as a framework.
 // This lines up to the name used in the CocoaPod.

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

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

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

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