HeaderDoc support in the library and generated sources

- Convert most of the core library headers over to HeaderDoc format.
- Switch the generated comments over to HeaderDoc.
- Create GPBCodedOutputStream_PackagePrivate and move some things into there
  that should be more internal.

1 files changed, 59 insertions, 57 deletions

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