Skip to content

Commit

Permalink
Migrating documentation of the ObjectiveC runtime code to appledoc. (p…
Browse files Browse the repository at this point in the history 
…rotocolbuffers#1867)

Work for protocolbuffers#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.
  • Loading branch information
@sergiocampama @thomasvl
sergiocampama authored and thomasvl committed Aug 8, 2016
1 parent 1102a8a commit 32fadc0
Show file tree
Hide file tree
Showing 14 changed files with 9,524 additions and 774 deletions.
1,448 changes: 1,433 additions & 15 deletions objectivec/GPBArray.h
View file

Large diffs are not rendered by default.

37 changes: 27 additions & 10 deletions objectivec/GPBBootstrap.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,13 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

// The Objective C runtime has complete enough info that most protos don’t end
// up using this, so leaving it on is no cost or very little cost. If you
// happen to see it causing bloat, this is the way to disable it. If you do
// need to disable it, try only disabling it for Release builds as having
// full TextFormat can be useful for debugging.
/**
* The Objective C runtime has complete enough info that most protos don’t end
* up using this, so leaving it on is no cost or very little cost. If you
* happen to see it causing bloat, this is the way to disable it. If you do
* need to disable it, try only disabling it for Release builds as having
* full TextFormat can be useful for debugging.
**/
#ifndef GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS
#define GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS 0
#endif
Expand All @@ -42,6 +44,7 @@
#if !__has_feature(objc_fixed_enum)
#error All supported Xcode versions should support objc_fixed_enum.
#endif

// If the headers are imported into Objective-C++, we can run into an issue
// where the defintion of NS_ENUM (really CF_ENUM) changes based on the C++
// standard that is in effect. If it isn't C++11 or higher, the definition
Expand All @@ -53,19 +56,29 @@
#else
#define GPB_ENUM(X) NS_ENUM(int32_t, X)
#endif
// GPB_ENUM_FWD_DECLARE is used for forward declaring enums, ex:
// GPB_ENUM_FWD_DECLARE(Foo_Enum)
// @property (nonatomic) Foo_Enum value;

/**
* GPB_ENUM_FWD_DECLARE is used for forward declaring enums, for example:
*
* ```
* GPB_ENUM_FWD_DECLARE(Foo_Enum)
* @property (nonatomic) Foo_Enum value;
* ```
**/
#define GPB_ENUM_FWD_DECLARE(X) enum X : int32_t

// Based upon CF_INLINE. Forces inlining in release.
/**
* Based upon CF_INLINE. Forces inlining in non DEBUG builds.
**/
#if !defined(DEBUG)
#define GPB_INLINE static __inline__ __attribute__((always_inline))
#else
#define GPB_INLINE static __inline__
#endif

// For use in public headers that might need to deal with ARC.
/**
* For use in public headers that might need to deal with ARC.
**/
#ifndef GPB_UNSAFE_UNRETAINED
#if __has_feature(objc_arc)
#define GPB_UNSAFE_UNRETAINED __unsafe_unretained
Expand All @@ -76,10 +89,14 @@

// If property name starts with init we need to annotate it to get past ARC.
// http://stackoverflow.com/questions/18723226/how-do-i-annotate-an-objective-c-property-with-an-objc-method-family/18723227#18723227
//
// Meant to be used internally by generated code.
#define GPB_METHOD_FAMILY_NONE __attribute__((objc_method_family(none)))

// The protoc-gen-objc version which works with the current version of the
// generated Objective C sources. In general we don't want to change the
// runtime interfaces (or this version) as it means everything has to be
// regenerated.
//
// Meant to be used internally by generated code.
#define GOOGLE_PROTOBUF_OBJC_GEN_VERSION 30001
199 changes: 134 additions & 65 deletions objectivec/GPBCodedInputStream.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,125 +37,194 @@ NS_ASSUME_NONNULL_BEGIN

CF_EXTERN_C_BEGIN

/// GPBCodedInputStream exception name. Exceptions raised from
/// GPBCodedInputStream contain an underlying error in the userInfo dictionary
/// under the GPBCodedInputStreamUnderlyingErrorKey key.
/**
* @c GPBCodedInputStream exception name. Exceptions raised from
* @c GPBCodedInputStream contain an underlying error in the userInfo dictionary
* under the GPBCodedInputStreamUnderlyingErrorKey key.
**/
extern NSString *const GPBCodedInputStreamException;

/// The key under which the underlying NSError from the exception is stored.
/** The key under which the underlying NSError from the exception is stored. */
extern NSString *const GPBCodedInputStreamUnderlyingErrorKey;

/// NSError domain used for GPBCodedInputStream errors.
/** NSError domain used for @c GPBCodedInputStream errors. */
extern NSString *const GPBCodedInputStreamErrorDomain;

/// Error code for NSError with GPBCodedInputStreamErrorDomain.
/**
* Error code for NSError with @c GPBCodedInputStreamErrorDomain.
**/
typedef NS_ENUM(NSInteger, GPBCodedInputStreamErrorCode) {
/// The size does not fit in the remaining bytes to be read.
/** The size does not fit in the remaining bytes to be read. */
GPBCodedInputStreamErrorInvalidSize = -100,
/// Attempted to read beyond the subsection limit.
/** Attempted to read beyond the subsection limit. */
GPBCodedInputStreamErrorSubsectionLimitReached = -101,
/// The requested subsection limit is invalid.
/** The requested subsection limit is invalid. */
GPBCodedInputStreamErrorInvalidSubsectionLimit = -102,
/// Invalid tag read.
/** Invalid tag read. */
GPBCodedInputStreamErrorInvalidTag = -103,
/// Invalid UTF-8 character in a string.
/** Invalid UTF-8 character in a string. */
GPBCodedInputStreamErrorInvalidUTF8 = -104,
/// Invalid VarInt read.
/** Invalid VarInt read. */
GPBCodedInputStreamErrorInvalidVarInt = -105,
/// The maximum recursion depth of messages was exceeded.
/** The maximum recursion depth of messages was exceeded. */
GPBCodedInputStreamErrorRecursionDepthExceeded = -106,
};

CF_EXTERN_C_END

/// Reads and decodes protocol message fields.
///
/// The common uses of protocol buffers shouldn't need to use this class.
/// @c GPBMessage's provide a @c +parseFromData:error: and @c
/// +parseFromData:extensionRegistry:error: method that will decode a
/// message for you.
///
/// @note Subclassing of GPBCodedInputStream is NOT supported.
/**
* Reads and decodes protocol message fields.
*
* The common uses of protocol buffers shouldn't need to use this class.
* @c GPBMessage's provide a @c +parseFromData:error: and
* @c +parseFromData:extensionRegistry:error: method that will decode a
* message for you.
*
* @note Subclassing of @c GPBCodedInputStream is NOT supported.
**/
@interface GPBCodedInputStream : NSObject

/// Creates a new stream wrapping some data.
/**
* Creates a new stream wrapping some data.
*
* @param data The data to wrap inside the stream.
*
* @return A newly instanced GPBCodedInputStream.
**/
+ (instancetype)streamWithData:(NSData *)data;

/// Initializes a stream wrapping some data.
/**
* Initializes a stream wrapping some data.
*
* @param data The data to wrap inside the stream.
*
* @return A newly initialized GPBCodedInputStream.
**/
- (instancetype)initWithData:(NSData *)data;

/// Attempt to read a field tag, returning zero if we have reached EOF.
/// Protocol message parsers use this to read tags, since a protocol message
/// may legally end wherever a tag occurs, and zero is not a valid tag number.
/**
* Attempts to read a field tag, returning zero if we have reached EOF.
* Protocol message parsers use this to read tags, since a protocol message
* may legally end wherever a tag occurs, and zero is not a valid tag number.
*
* @return The field tag, or zero if EOF was reached.
**/
- (int32_t)readTag;

/// Read and return a double.
/**
* @return A double read from the stream.
**/
- (double)readDouble;
/// Read and return a float.
/**
* @return A float read from the stream.
**/
- (float)readFloat;
/// Read and return a uint64.
/**
* @return A uint64 read from the stream.
**/
- (uint64_t)readUInt64;
/// Read and return a uint32.
/**
* @return A uint32 read from the stream.
**/
- (uint32_t)readUInt32;
/// Read and return an int64.
/**
* @return An int64 read from the stream.
**/
- (int64_t)readInt64;
/// Read and return an int32.
/**
* @return An int32 read from the stream.
**/
- (int32_t)readInt32;
/// Read and return a fixed64.
/**
* @return A fixed64 read from the stream.
**/
- (uint64_t)readFixed64;
/// Read and return a fixed32.
/**
* @return A fixed32 read from the stream.
**/
- (uint32_t)readFixed32;
/// Read and return an enum (int).
/**
* @return An enum read from the stream.
**/
- (int32_t)readEnum;
/// Read and return a sfixed32.
/**
* @return A sfixed32 read from the stream.
**/
- (int32_t)readSFixed32;
/// Read and return a sfixed64.
/**
* @return A fixed64 read from the stream.
**/
- (int64_t)readSFixed64;
/// Read and return a sint32.
/**
* @return A sint32 read from the stream.
**/
- (int32_t)readSInt32;
/// Read and return a sint64.
/**
* @return A sint64 read from the stream.
**/
- (int64_t)readSInt64;
/// Read and return a boolean.
/**
* @return A boolean read from the stream.
**/
- (BOOL)readBool;
/// Read and return a string.
/**
* @return A string read from the stream.
**/
- (NSString *)readString;
/// Read and return length delimited data.
/**
* @return Data read from the stream.
**/
- (NSData *)readBytes;

/// Read an embedded message field value from the stream.
///
/// @param message The message to set fields on as they are read.
/// @param extensionRegistry An optional extension registry to use to lookup
/// extensions for @c message.
/**
* Read an embedded message field value from the stream.
*
* @param message The message to set fields on as they are read.
* @param extensionRegistry An optional extension registry to use to lookup
* extensions for message.
**/
- (void)readMessage:(GPBMessage *)message
extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;

/// Reads and discards a single field, given its tag value.
///
/// @param tag The tag number of the field to skip.
///
/// @return NO if the tag is an endgroup tag (in which case nothing is skipped),
/// YES in all other cases.
/**
* Reads and discards a single field, given its tag value.
*
* @param tag The tag number of the field to skip.
*
* @return NO if the tag is an endgroup tag (in which case nothing is skipped),
* YES in all other cases.
**/
- (BOOL)skipField:(int32_t)tag;

/// Reads and discards an entire message. This will read either until EOF
/// or until an endgroup tag, whichever comes first.
/**
* Reads and discards an entire message. This will read either until EOF or
* until an endgroup tag, whichever comes first.
**/
- (void)skipMessage;

/// Check to see if the logical end of the stream has been reached.
///
/// This can return NO when there is no more data, but the current parsing
/// expected more data.
/**
* Check to see if the logical end of the stream has been reached.
*
* @note This can return NO when there is no more data, but the current parsing
* expected more data.
*
* @return YES if the logical end of the stream has been reached, NO otherwise.
**/
- (BOOL)isAtEnd;

/// The offset into the stream.
/**
* @return The offset into the stream.
**/
- (size_t)position;

/// Verifies that the last call to @c -readTag returned the given tag value.
/// This is used to verify that a nested group ended with the correct end tag.
/// Throws @c NSParseErrorException if value does not match the last tag.
///
/// @param expected The tag that was expected.
/**
* Verifies that the last call to -readTag returned the given tag value. This
* is used to verify that a nested group ended with the correct end tag.
*
* @exception NSParseErrorException If the value does not match the last tag.
*
* @param expected The tag that was expected.
**/
- (void)checkLastTagWas:(int32_t)expected;

@end
Expand Down
Loading

0 comments on commit 32fadc0

Please sign in to comment.