From 42ab9b444207dd7112ef9609a2c7865c0610fa38 Mon Sep 17 00:00:00 2001 From: Sergio Campamá Date: Mon, 8 Aug 2016 07:15:02 -0700 Subject: Migrating documentation of the ObjectiveC runtime code to appledoc. (#1867) Work for #1866 Migrates all the public class docs over to appledoc format. While Xcode is fine with blank lines in `///` comments, appledoc (used by cocoadocs) isn't and was leaving a bunch of info off the doc pages. The generator still needs to be updated to do this also; that will be a follow up CL. --- objectivec/GPBUtilities.h | 493 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 385 insertions(+), 108 deletions(-) (limited to 'objectivec/GPBUtilities.h') 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); //% -- cgit v1.2.3