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

Work for #1866 

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

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

1 files changed, 385 insertions, 108 deletions

diff --git a/objectivec/GPBUtilities.h b/objectivec/GPBUtilities.h
index b7209324..52e7d2e0 100644
--- a/objectivec/GPBUtilities.h
+++ b/objectivec/GPBUtilities.h
@@ -38,34 +38,58 @@ CF_EXTERN_C_BEGIN
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// Generates a string that should be a valid "Text Format" for the C++ version
-/// of Protocol Buffers.
-///
-///  @param message    The message to generate from.
-///  @param lineIndent A string to use as the prefix for all lines generated. Can
-///                    be nil if no extra indent is needed.
-///
-/// @return A @c NSString with the Text Format of the message.
+/**
+ * Generates a string that should be a valid "TextFormat" for the C++ version
+ * of Protocol Buffers.
+ *
+ * @param message    The message to generate from.
+ * @param lineIndent A string to use as the prefix for all lines generated. Can
+ *                   be nil if no extra indent is needed.
+ *
+ * @return An NSString with the TextFormat of the message.
+ **/
 NSString *GPBTextFormatForMessage(GPBMessage *message,
                                   NSString * __nullable lineIndent);
 
-/// Generates a string that should be a valid "Text Format" for the C++ version
-/// of Protocol Buffers.
-///
-///  @param unknownSet The unknown field set to generate from.
-///  @param lineIndent A string to use as the prefix for all lines generated. Can
-///                    be nil if no extra indent is needed.
-///
-/// @return A @c NSString with the Text Format of the unknown field set.
+/**
+ * Generates a string that should be a valid "TextFormat" for the C++ version
+ * of Protocol Buffers.
+ *
+ * @param unknownSet The unknown field set to generate from.
+ * @param lineIndent A string to use as the prefix for all lines generated. Can
+ *                   be nil if no extra indent is needed.
+ *
+ * @return An NSString with the TextFormat of the unknown field set.
+ **/
 NSString *GPBTextFormatForUnknownFieldSet(GPBUnknownFieldSet * __nullable unknownSet,
                                           NSString * __nullable lineIndent);
 
-/// Test if the given field is set on a message.
+/**
+ * Checks if the given field number is set on a message.
+ *
+ * @param self        The message to check.
+ * @param fieldNumber The field number to check.
+ *
+ * @return YES if the field number is set on the given message.
+ **/
 BOOL GPBMessageHasFieldNumberSet(GPBMessage *self, uint32_t fieldNumber);
-/// Test if the given field is set on a message.
+
+/**
+ * Checks if the given field is set on a message.
+ *
+ * @param self  The message to check.
+ * @param field The field to check.
+ *
+ * @return YES if the field is set on the given message.
+ **/
 BOOL GPBMessageHasFieldSet(GPBMessage *self, GPBFieldDescriptor *field);
 
-/// Clear the given field of a message.
+/**
+ * Clears the given field for the given message.
+ *
+ * @param self  The message for which to clear the field.
+ * @param field The field to clear.
+ **/
 void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field);
 
 //%PDDM-EXPAND GPB_ACCESSORS()
@@ -73,112 +97,299 @@ void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field);
 
 
 //
-// Get/Set the given field of a message.
+// Get/Set a given field from/to a message.
 //
 
 // Single Fields
 
-/// Gets the value of a bytes field.
+/**
+ * Gets the value of a bytes field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 NSData *GPBGetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a bytes field.
+
+/**
+ * Sets the value of a bytes field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field, NSData *value);
 
-/// Gets the value of a string field.
+/**
+ * Gets the value of a string field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 NSString *GPBGetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a string field.
+
+/**
+ * Sets the value of a string field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field, NSString *value);
 
-/// Gets the value of a message field.
+/**
+ * Gets the value of a message field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 GPBMessage *GPBGetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a message field.
+
+/**
+ * Sets the value of a message field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value);
 
-/// Gets the value of a group field.
+/**
+ * Gets the value of a group field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 GPBMessage *GPBGetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a group field.
+
+/**
+ * Sets the value of a group field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value);
 
-/// Gets the value of a bool field.
+/**
+ * Gets the value of a bool field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 BOOL GPBGetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a bool field.
+
+/**
+ * Sets the value of a bool field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field, BOOL value);
 
-/// Gets the value of an int32 field.
+/**
+ * Gets the value of an int32 field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 int32_t GPBGetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of an int32 field.
+
+/**
+ * Sets the value of an int32 field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
 
-/// Gets the value of an uint32 field.
+/**
+ * Gets the value of an uint32 field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 uint32_t GPBGetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of an uint32 field.
+
+/**
+ * Sets the value of an uint32 field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field, uint32_t value);
 
-/// Gets the value of an int64 field.
+/**
+ * Gets the value of an int64 field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 int64_t GPBGetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of an int64 field.
+
+/**
+ * Sets the value of an int64 field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field, int64_t value);
 
-/// Gets the value of an uint64 field.
+/**
+ * Gets the value of an uint64 field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 uint64_t GPBGetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of an uint64 field.
+
+/**
+ * Sets the value of an uint64 field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field, uint64_t value);
 
-/// Gets the value of a float field.
+/**
+ * Gets the value of a float field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 float GPBGetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a float field.
+
+/**
+ * Sets the value of a float field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field, float value);
 
-/// Gets the value of a double field.
+/**
+ * Gets the value of a double field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ **/
 double GPBGetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a double field.
+
+/**
+ * Sets the value of a double field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The to set in the field.
+ **/
 void GPBSetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field, double value);
 
-/// Get the given enum field of a message. For proto3, if the value isn't a
-/// member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned.
-/// GPBGetMessageRawEnumField will bypass the check and return whatever value
-/// was set.
+/**
+ * Gets the given enum field of a message. For proto3, if the value isn't a
+ * member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned.
+ * GPBGetMessageRawEnumField will bypass the check and return whatever value
+ * was set.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ *
+ * @return The enum value for the given field.
+ **/
 int32_t GPBGetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Set the given enum field of a message. You can only set values that are
-/// members of the enum.
-void GPBSetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
-/// Get the given enum field of a message. No check is done to ensure the value
-/// was defined in the enum.
+
+/**
+ * Set the given enum field of a message. You can only set values that are
+ * members of the enum.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The enum value to set in the field.
+ **/
+void GPBSetMessageEnumField(GPBMessage *self,
+                            GPBFieldDescriptor *field,
+                            int32_t value);
+
+/**
+ * Get the given enum field of a message. No check is done to ensure the value
+ * was defined in the enum.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The field to get.
+ *
+ * @return The raw enum value for the given field.
+ **/
 int32_t GPBGetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Set the given enum field of a message. You can set the value to anything,
-/// even a value that is not a member of the enum.
-void GPBSetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
+
+/**
+ * Set the given enum field of a message. You can set the value to anything,
+ * even a value that is not a member of the enum.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param value The raw enum value to set in the field.
+ **/
+void GPBSetMessageRawEnumField(GPBMessage *self,
+                               GPBFieldDescriptor *field,
+                               int32_t value);
 
 // Repeated Fields
 
-/// Gets the value of a repeated field.
-///
-/// The result will be @c GPB*Array or @c NSMutableArray based on the
-/// field's type.
+/**
+ * Gets the value of a repeated field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The repeated field to get.
+ *
+ * @return A GPB*Array or an NSMutableArray based on the field's type.
+ **/
 id GPBGetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a repeated field.
-///
-/// The value should be @c GPB*Array or @c NSMutableArray based on the
-/// field's type.
-void GPBSetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field, id array);
+
+/**
+ * Sets the value of a repeated field.
+ *
+ * @param self  The message into which to set the field.
+ * @param field The field to set.
+ * @param array A GPB*Array or NSMutableArray based on the field's type.
+ **/
+void GPBSetMessageRepeatedField(GPBMessage *self,
+                                GPBFieldDescriptor *field,
+                                id array);
 
 // Map Fields
 
-/// Gets the value of a map<> field.
-///
-/// The result will be @c GPB*Dictionary or @c NSMutableDictionary based on
-/// the field's type.
+/**
+ * Gets the value of a map<> field.
+ *
+ * @param self  The message from which to get the field.
+ * @param field The repeated field to get.
+ *
+ * @return A GPB*Dictionary or NSMutableDictionary based on the field's type.
+ **/
 id GPBGetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field);
-/// Sets the value of a map<> field.
-///
-/// The object should be @c GPB*Dictionary or @c NSMutableDictionary based
-/// on the field's type.
-void GPBSetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field, id dictionary);
+
+/**
+ * Sets the value of a map<> field.
+ *
+ * @param self       The message into which to set the field.
+ * @param field      The field to set.
+ * @param dictionary A GPB*Dictionary or NSMutableDictionary based on the
+ *                   field's type.
+ **/
+void GPBSetMessageMapField(GPBMessage *self,
+                           GPBFieldDescriptor *field,
+                           id dictionary);
 
 //%PDDM-EXPAND-END GPB_ACCESSORS()
 
-// Returns an empty NSData to assign to byte fields when you wish
-// to assign them to empty. Prevents allocating a lot of little [NSData data]
-// objects.
+/**
+ * Returns an empty NSData to assign to byte fields when you wish to assign them
+ * to empty. Prevents allocating a lot of little [NSData data] objects.
+ **/
 NSData *GPBEmptyNSData(void) __attribute__((pure));
 
 NS_ASSUME_NONNULL_END
@@ -189,7 +400,7 @@ CF_EXTERN_C_END
 //%PDDM-DEFINE GPB_ACCESSORS()
 //%
 //%//
-//%// Get/Set the given field of a message.
+//%// Get/Set a given field from/to a message.
 //%//
 //%
 //%// Single Fields
@@ -205,53 +416,119 @@ CF_EXTERN_C_END
 //%GPB_ACCESSOR_SINGLE(UInt64, uint64_t, n)
 //%GPB_ACCESSOR_SINGLE(Float, float, )
 //%GPB_ACCESSOR_SINGLE(Double, double, )
-//%/// Get the given enum field of a message. For proto3, if the value isn't a
-//%/// member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned.
-//%/// GPBGetMessageRawEnumField will bypass the check and return whatever value
-//%/// was set.
+//%/**
+//% * Gets the given enum field of a message. For proto3, if the value isn't a
+//% * member of the enum, @c kGPBUnrecognizedEnumeratorValue will be returned.
+//% * GPBGetMessageRawEnumField will bypass the check and return whatever value
+//% * was set.
+//% *
+//% * @param self  The message from which to get the field.
+//% * @param field The field to get.
+//% *
+//% * @return The enum value for the given field.
+//% **/
 //%int32_t GPBGetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field);
-//%/// Set the given enum field of a message. You can only set values that are
-//%/// members of the enum.
-//%void GPBSetMessageEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
-//%/// Get the given enum field of a message. No check is done to ensure the value
-//%/// was defined in the enum.
+//%
+//%/**
+//% * Set the given enum field of a message. You can only set values that are
+//% * members of the enum.
+//% *
+//% * @param self  The message into which to set the field.
+//% * @param field The field to set.
+//% * @param value The enum value to set in the field.
+//% **/
+//%void GPBSetMessageEnumField(GPBMessage *self,
+//%                            GPBFieldDescriptor *field,
+//%                            int32_t value);
+//%
+//%/**
+//% * Get the given enum field of a message. No check is done to ensure the value
+//% * was defined in the enum.
+//% *
+//% * @param self  The message from which to get the field.
+//% * @param field The field to get.
+//% *
+//% * @return The raw enum value for the given field.
+//% **/
 //%int32_t GPBGetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field);
-//%/// Set the given enum field of a message. You can set the value to anything,
-//%/// even a value that is not a member of the enum.
-//%void GPBSetMessageRawEnumField(GPBMessage *self, GPBFieldDescriptor *field, int32_t value);
+//%
+//%/**
+//% * Set the given enum field of a message. You can set the value to anything,
+//% * even a value that is not a member of the enum.
+//% *
+//% * @param self  The message into which to set the field.
+//% * @param field The field to set.
+//% * @param value The raw enum value to set in the field.
+//% **/
+//%void GPBSetMessageRawEnumField(GPBMessage *self,
+//%                               GPBFieldDescriptor *field,
+//%                               int32_t value);
 //%
 //%// Repeated Fields
 //%
-//%/// Gets the value of a repeated field.
-//%///
-//%/// The result will be @c GPB*Array or @c NSMutableArray based on the
-//%/// field's type.
+//%/**
+//% * Gets the value of a repeated field.
+//% *
+//% * @param self  The message from which to get the field.
+//% * @param field The repeated field to get.
+//% *
+//% * @return A GPB*Array or an NSMutableArray based on the field's type.
+//% **/
 //%id GPBGetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field);
-//%/// Sets the value of a repeated field.
-//%///
-//%/// The value should be @c GPB*Array or @c NSMutableArray based on the
-//%/// field's type.
-//%void GPBSetMessageRepeatedField(GPBMessage *self, GPBFieldDescriptor *field, id array);
+//%
+//%/**
+//% * Sets the value of a repeated field.
+//% *
+//% * @param self  The message into which to set the field.
+//% * @param field The field to set.
+//% * @param array A GPB*Array or NSMutableArray based on the field's type.
+//% **/
+//%void GPBSetMessageRepeatedField(GPBMessage *self,
+//%                                GPBFieldDescriptor *field,
+//%                                id array);
 //%
 //%// Map Fields
 //%
-//%/// Gets the value of a map<> field.
-//%///
-//%/// The result will be @c GPB*Dictionary or @c NSMutableDictionary based on
-//%/// the field's type.
+//%/**
+//% * Gets the value of a map<> field.
+//% *
+//% * @param self  The message from which to get the field.
+//% * @param field The repeated field to get.
+//% *
+//% * @return A GPB*Dictionary or NSMutableDictionary based on the field's type.
+//% **/
 //%id GPBGetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field);
-//%/// Sets the value of a map<> field.
-//%///
-//%/// The object should be @c GPB*Dictionary or @c NSMutableDictionary based
-//%/// on the field's type.
-//%void GPBSetMessageMapField(GPBMessage *self, GPBFieldDescriptor *field, id dictionary);
+//%
+//%/**
+//% * Sets the value of a map<> field.
+//% *
+//% * @param self       The message into which to set the field.
+//% * @param field      The field to set.
+//% * @param dictionary A GPB*Dictionary or NSMutableDictionary based on the
+//% *                   field's type.
+//% **/
+//%void GPBSetMessageMapField(GPBMessage *self,
+//%                           GPBFieldDescriptor *field,
+//%                           id dictionary);
 //%
 
 //%PDDM-DEFINE GPB_ACCESSOR_SINGLE(NAME, TYPE, AN)
 //%GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, AN, )
 //%PDDM-DEFINE GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, AN, TisP)
-//%/// Gets the value of a##AN NAME$L field.
+//%/**
+//% * Gets the value of a##AN NAME$L field.
+//% *
+//% * @param self  The message from which to get the field.
+//% * @param field The field to get.
+//% **/
 //%TYPE TisP##GPBGetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field);
-//%/// Sets the value of a##AN NAME$L field.
+//%
+//%/**
+//% * Sets the value of a##AN NAME$L field.
+//% *
+//% * @param self  The message into which to set the field.
+//% * @param field The field to set.
+//% * @param value The to set in the field.
+//% **/
 //%void GPBSetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field, TYPE TisP##value);
 //%