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.
diff --git a/objectivec/GPBCodedInputStream.h b/objectivec/GPBCodedInputStream.h
index 42a0494..0619888 100644
--- a/objectivec/GPBCodedInputStream.h
+++ b/objectivec/GPBCodedInputStream.h
@@ -35,52 +35,86 @@
NS_ASSUME_NONNULL_BEGIN
-// Reads and decodes protocol message fields.
-// 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 GPBCodedInputStream is NOT supported.
@interface GPBCodedInputStream : NSObject
+/// Creates a new stream wrapping some data.
+ (instancetype)streamWithData:(NSData *)data;
+
+/// Initializes a stream wrapping some data.
- (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.
+/// 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.
- (int32_t)readTag;
+/// Read and return a double.
- (double)readDouble;
+/// Read and return a float.
- (float)readFloat;
+/// Read and return a uint64.
- (uint64_t)readUInt64;
+/// Read and return a uint32.
- (uint32_t)readUInt32;
+/// Read and return an int64.
- (int64_t)readInt64;
+/// Read and return an int32.
- (int32_t)readInt32;
+/// Read and return a fixed64.
- (uint64_t)readFixed64;
+/// Read and return a fixed32.
- (uint32_t)readFixed32;
+/// Read and return an enum (int).
- (int32_t)readEnum;
+/// Read and return a sfixed32.
- (int32_t)readSFixed32;
+/// Read and return a sfixed64.
- (int64_t)readSFixed64;
+/// Read and return a sint32.
- (int32_t)readSInt32;
+/// Read and return a sint64.
- (int64_t)readSInt64;
+/// Read and return a boolean.
- (BOOL)readBool;
+/// Read and return a string.
- (NSString *)readString;
+/// Read and return length delimited data.
- (NSData *)readBytes;
-// Read an embedded message field value from the stream.
+/// 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;
+ extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
-// Reads and discards a single field, given its tag value. Returns NO if the
-// tag is an endgroup tag, in which case nothing is skipped. Otherwise,
-// returns YES.
+/// 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;
-// 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.
-// Throws NSParseErrorException if value does not match the last tag.
-- (void)checkLastTagWas:(int32_t)value;
+/// 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.
+- (void)checkLastTagWas:(int32_t)expected;
@end
