From 36650a07cf98ee4e734e07f2403fe5d20e300fc8 Mon Sep 17 00:00:00 2001 From: Thomas Van Lenten Date: Mon, 7 Mar 2016 12:07:03 -0500 Subject: 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. --- objectivec/GPBUtilities.h | 150 +++++++++++++++++++++++++++++++++------------- 1 file changed, 110 insertions(+), 40 deletions(-) (limited to 'objectivec/GPBUtilities.h') diff --git a/objectivec/GPBUtilities.h b/objectivec/GPBUtilities.h index 5b55104b..b7209324 100644 --- a/objectivec/GPBUtilities.h +++ b/objectivec/GPBUtilities.h @@ -38,24 +38,34 @@ 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. lineIndent can be nil if no additional line indent is -// needed. The comments provide the names according to the ObjC library, they -// most likely won't exactly match the original .proto file. +/// 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. 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. NSString *GPBTextFormatForUnknownFieldSet(GPBUnknownFieldSet * __nullable unknownSet, NSString * __nullable lineIndent); -// -// Test if the given field is set on a message. -// +/// Test if the given field is set on a message. BOOL GPBMessageHasFieldNumberSet(GPBMessage *self, uint32_t fieldNumber); +/// Test if the given field is set on a message. BOOL GPBMessageHasFieldSet(GPBMessage *self, GPBFieldDescriptor *field); -// -// Clear the given field of a message. -// +/// Clear the given field of a message. void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field); //%PDDM-EXPAND GPB_ACCESSORS() @@ -68,60 +78,100 @@ void GPBClearMessageField(GPBMessage *self, GPBFieldDescriptor *field); // Single Fields +/// Gets the value of a bytes field. NSData *GPBGetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of a bytes field. void GPBSetMessageBytesField(GPBMessage *self, GPBFieldDescriptor *field, NSData *value); +/// Gets the value of a string field. NSString *GPBGetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of a string field. void GPBSetMessageStringField(GPBMessage *self, GPBFieldDescriptor *field, NSString *value); +/// Gets the value of a message field. GPBMessage *GPBGetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of a message field. void GPBSetMessageMessageField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value); +/// Gets the value of a group field. GPBMessage *GPBGetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of a group field. void GPBSetMessageGroupField(GPBMessage *self, GPBFieldDescriptor *field, GPBMessage *value); +/// Gets the value of a bool field. BOOL GPBGetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of a bool field. void GPBSetMessageBoolField(GPBMessage *self, GPBFieldDescriptor *field, BOOL value); +/// Gets the value of an int32 field. int32_t GPBGetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of an int32 field. void GPBSetMessageInt32Field(GPBMessage *self, GPBFieldDescriptor *field, int32_t value); +/// Gets the value of an uint32 field. uint32_t GPBGetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of an uint32 field. void GPBSetMessageUInt32Field(GPBMessage *self, GPBFieldDescriptor *field, uint32_t value); +/// Gets the value of an int64 field. int64_t GPBGetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of an int64 field. void GPBSetMessageInt64Field(GPBMessage *self, GPBFieldDescriptor *field, int64_t value); +/// Gets the value of an uint64 field. uint64_t GPBGetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of an uint64 field. void GPBSetMessageUInt64Field(GPBMessage *self, GPBFieldDescriptor *field, uint64_t value); +/// Gets the value of a float field. float GPBGetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of a float field. void GPBSetMessageFloatField(GPBMessage *self, GPBFieldDescriptor *field, float value); +/// Gets the value of a double field. double GPBGetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field); +/// Sets the value of a double field. void GPBSetMessageDoubleField(GPBMessage *self, GPBFieldDescriptor *field, double value); -// Get/Set the given enum field of a message. You can only Set values that are -// members of the enum. For proto3, when doing a Get, if the value isn't a -// memeber of the enum, kGPBUnrecognizedEnumeratorValue will be returned. The -// the functions with "Raw" in the will bypass all checks. +/// 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. 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. 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); // Repeated Fields -// The object will/should be GPB*Array or NSMutableArray based on the field's -// type. +/// Gets the value of a repeated field. +/// +/// The result will be @c GPB*Array or @c 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); // Map Fields -// The object will/should be GPB*Dictionary or NSMutableDictionary based on the -// field's type. +/// Gets the value of a map<> field. +/// +/// The result will be @c GPB*Dictionary or @c 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); //%PDDM-EXPAND-END GPB_ACCESSORS() @@ -144,44 +194,64 @@ CF_EXTERN_C_END //% //%// Single Fields //% -//%GPB_ACCESSOR_SINGLE_FULL(Bytes, NSData, *) -//%GPB_ACCESSOR_SINGLE_FULL(String, NSString, *) -//%GPB_ACCESSOR_SINGLE_FULL(Message, GPBMessage, *) -//%GPB_ACCESSOR_SINGLE_FULL(Group, GPBMessage, *) -//%GPB_ACCESSOR_SINGLE(Bool, BOOL) -//%GPB_ACCESSOR_SINGLE(Int32, int32_t) -//%GPB_ACCESSOR_SINGLE(UInt32, uint32_t) -//%GPB_ACCESSOR_SINGLE(Int64, int64_t) -//%GPB_ACCESSOR_SINGLE(UInt64, uint64_t) -//%GPB_ACCESSOR_SINGLE(Float, float) -//%GPB_ACCESSOR_SINGLE(Double, double) -//%// Get/Set the given enum field of a message. You can only Set values that are -//%// members of the enum. For proto3, when doing a Get, if the value isn't a -//%// memeber of the enum, kGPBUnrecognizedEnumeratorValue will be returned. The -//%// the functions with "Raw" in the will bypass all checks. +//%GPB_ACCESSOR_SINGLE_FULL(Bytes, NSData, , *) +//%GPB_ACCESSOR_SINGLE_FULL(String, NSString, , *) +//%GPB_ACCESSOR_SINGLE_FULL(Message, GPBMessage, , *) +//%GPB_ACCESSOR_SINGLE_FULL(Group, GPBMessage, , *) +//%GPB_ACCESSOR_SINGLE(Bool, BOOL, ) +//%GPB_ACCESSOR_SINGLE(Int32, int32_t, n) +//%GPB_ACCESSOR_SINGLE(UInt32, uint32_t, n) +//%GPB_ACCESSOR_SINGLE(Int64, int64_t, n) +//%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. //%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. //%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); //% //%// Repeated Fields //% -//%// The object will/should be GPB*Array or NSMutableArray based on the field's -//%// type. +//%/// Gets the value of a repeated field. +//%/// +//%/// The result will be @c GPB*Array or @c 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); //% //%// Map Fields //% -//%// The object will/should be GPB*Dictionary or NSMutableDictionary based on the -//%// field's type. +//%/// Gets the value of a map<> field. +//%/// +//%/// The result will be @c GPB*Dictionary or @c 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); //% -//%PDDM-DEFINE GPB_ACCESSOR_SINGLE(NAME, TYPE) -//%GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, ) -//%PDDM-DEFINE GPB_ACCESSOR_SINGLE_FULL(NAME, TYPE, TisP) +//%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. //%TYPE TisP##GPBGetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field); +//%/// Sets the value of a##AN NAME$L field. //%void GPBSetMessage##NAME##Field(GPBMessage *self, GPBFieldDescriptor *field, TYPE TisP##value); //% -- cgit v1.2.3