diff --git a/src/objective-c/GRPCClient/GRPCCall+Tests.h b/src/objective-c/GRPCClient/GRPCCall+Tests.h index cca16146063..ccc5723ec70 100644 --- a/src/objective-c/GRPCClient/GRPCCall+Tests.h +++ b/src/objective-c/GRPCClient/GRPCCall+Tests.h @@ -33,22 +33,28 @@ #import "GRPCCall.h" -// Methods to let tune down the security of gRPC connections for specific hosts. These shouldn't be -// used in releases, but are sometimes needed for testing. +/** + * Methods to let tune down the security of gRPC connections for specific hosts. These shouldn't be + * used in releases, but are sometimes needed for testing. + */ @interface GRPCCall (Tests) -// Establish all SSL connections to the provided host using the passed SSL target name and the root -// certificates found in the file at |certsPath|. -// -// Must be called before any gRPC call to that host is made. It's illegal to pass the same host to -// more than one invocation of the methods of this category. +/** + * Establish all SSL connections to the provided host using the passed SSL target name and the root + * certificates found in the file at |certsPath|. + * + * Must be called before any gRPC call to that host is made. It's illegal to pass the same host to + * more than one invocation of the methods of this category. + */ + (void)useTestCertsPath:(NSString *)certsPath testName:(NSString *)testName forHost:(NSString *)host; -// Establish all connections to the provided host using cleartext instead of SSL. -// -// Must be called before any gRPC call to that host is made. It's illegal to pass the same host to -// more than one invocation of the methods of this category. +/** + * Establish all connections to the provided host using cleartext instead of SSL. + * + * Must be called before any gRPC call to that host is made. It's illegal to pass the same host to + * more than one invocation of the methods of this category. + */ + (void)useInsecureConnectionsForHost:(NSString *)host; @end diff --git a/src/objective-c/GRPCClient/GRPCCall.h b/src/objective-c/GRPCClient/GRPCCall.h index 86f4149c43e..91f2942c985 100644 --- a/src/objective-c/GRPCClient/GRPCCall.h +++ b/src/objective-c/GRPCClient/GRPCCall.h @@ -61,7 +61,7 @@ extern NSString *const kGRPCErrorDomain; * server applications to produce. */ typedef NS_ENUM(NSUInteger, GRPCErrorCode) { - // The operation was cancelled (typically by the caller). + /** The operation was cancelled (typically by the caller). */ GRPCErrorCodeCancelled = 1, /** diff --git a/src/objective-c/GRPCClient/private/GRPCChannel.h b/src/objective-c/GRPCClient/private/GRPCChannel.h index 2a7b701576a..e2d19d506ad 100644 --- a/src/objective-c/GRPCClient/private/GRPCChannel.h +++ b/src/objective-c/GRPCClient/private/GRPCChannel.h @@ -35,12 +35,16 @@ struct grpc_channel; -// Each separate instance of this class represents at least one TCP connection to the provided host. -// Create them using one of the subclasses |GRPCSecureChannel| and |GRPCUnsecuredChannel|. +/** + * Each separate instance of this class represents at least one TCP connection to the provided host. + * Create them using one of the subclasses |GRPCSecureChannel| and |GRPCUnsecuredChannel|. + */ @interface GRPCChannel : NSObject @property(nonatomic, readonly) struct grpc_channel *unmanagedChannel; -// This initializer takes ownership of the passed channel, and will destroy it when this object is -// deallocated. It's illegal to pass the same grpc_channel to two different GRPCChannel objects. +/** + * This initializer takes ownership of the passed channel, and will destroy it when this object is + * deallocated. It's illegal to pass the same grpc_channel to two different GRPCChannel objects. + */ - (instancetype)initWithChannel:(struct grpc_channel *)unmanagedChannel NS_DESIGNATED_INITIALIZER; @end diff --git a/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h b/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h index ab8d714d220..fe3b8f39d12 100644 --- a/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h +++ b/src/objective-c/GRPCClient/private/GRPCCompletionQueue.h @@ -36,15 +36,17 @@ typedef void(^GRPCQueueCompletionHandler)(bool success); -// This class lets one more easily use |grpc_completion_queue|. To use it, pass the value of the -// |unmanagedQueue| property of an instance of this class to |grpc_channel_create_call|. Then for -// every |grpc_call_*| method that accepts a tag, you can pass a block of type -// |GRPCQueueCompletionHandler| (remembering to cast it using |__bridge_retained|). The block is -// guaranteed to eventually be called, by a concurrent queue, and then released. Each such block is -// passed a |bool| that tells if the operation was successful. -// -// Release the GRPCCompletionQueue object only after you are not going to pass any more blocks to -// the |grpc_call| that's using it. +/** + * This class lets one more easily use |grpc_completion_queue|. To use it, pass the value of the + * |unmanagedQueue| property of an instance of this class to |grpc_channel_create_call|. Then for + * every |grpc_call_*| method that accepts a tag, you can pass a block of type + * |GRPCQueueCompletionHandler| (remembering to cast it using |__bridge_retained|). The block is + * guaranteed to eventually be called, by a concurrent queue, and then released. Each such block is + * passed a |bool| that tells if the operation was successful. + * + * Release the GRPCCompletionQueue object only after you are not going to pass any more blocks to + * the |grpc_call| that's using it. + */ @interface GRPCCompletionQueue : NSObject @property(nonatomic, readonly) grpc_completion_queue *unmanagedQueue; diff --git a/src/objective-c/GRPCClient/private/GRPCHost.h b/src/objective-c/GRPCClient/private/GRPCHost.h index f0bbd530234..6b4f98746d0 100644 --- a/src/objective-c/GRPCClient/private/GRPCHost.h +++ b/src/objective-c/GRPCClient/private/GRPCHost.h @@ -40,18 +40,18 @@ struct grpc_call; @property(nonatomic, readonly) NSString *address; -// The following properties should only be modified for testing: +/** The following properties should only be modified for testing: */ @property(nonatomic, getter=isSecure) BOOL secure; @property(nonatomic, copy) NSString *pathToCertificates; @property(nonatomic, copy) NSString *hostNameOverride; -// Host objects initialized with the same address are the same. +/** Host objects initialized with the same address are the same. */ + (instancetype)hostWithAddress:(NSString *)address; - (instancetype)initWithAddress:(NSString *)address NS_DESIGNATED_INITIALIZER; -// Create a grpc_call object to the provided path on this host. +/** Create a grpc_call object to the provided path on this host. */ - (struct grpc_call *)unmanagedCallWithPath:(NSString *)path completionQueue:(GRPCCompletionQueue *)queue; diff --git a/src/objective-c/GRPCClient/private/GRPCSecureChannel.h b/src/objective-c/GRPCClient/private/GRPCSecureChannel.h index 74257eb0584..4e0881e5a2a 100644 --- a/src/objective-c/GRPCClient/private/GRPCSecureChannel.h +++ b/src/objective-c/GRPCClient/private/GRPCSecureChannel.h @@ -40,13 +40,15 @@ struct grpc_credentials; @interface GRPCSecureChannel : GRPCChannel - (instancetype)initWithHost:(NSString *)host; -// Only in tests shouldn't pathToCertificates or hostNameOverride be nil. Passing nil for -// pathToCertificates results in using the default root certificates distributed with the library. +/** + * Only in tests shouldn't pathToCertificates or hostNameOverride be nil. Passing nil for + * pathToCertificates results in using the default root certificates distributed with the library. + */ - (instancetype)initWithHost:(NSString *)host pathToCertificates:(NSString *)path hostNameOverride:(NSString *)hostNameOverride; -// The passed arguments aren't required to be valid beyond the invocation of this initializer. +/** The passed arguments aren't required to be valid beyond the invocation of this initializer. */ - (instancetype)initWithHost:(NSString *)host credentials:(struct grpc_credentials *)credentials args:(grpc_channel_args *)args NS_DESIGNATED_INITIALIZER; diff --git a/src/objective-c/GRPCClient/private/GRPCWrappedCall.h b/src/objective-c/GRPCClient/private/GRPCWrappedCall.h index 4ca2766147e..7747aa53ef0 100644 --- a/src/objective-c/GRPCClient/private/GRPCWrappedCall.h +++ b/src/objective-c/GRPCClient/private/GRPCWrappedCall.h @@ -39,7 +39,7 @@ @interface GRPCOperation : NSObject @property(nonatomic, readonly) grpc_op op; -// Guaranteed to be called when the operation has finished. +/** Guaranteed to be called when the operation has finished. */ - (void)finish; @end diff --git a/src/objective-c/GRPCClient/private/NSError+GRPC.h b/src/objective-c/GRPCClient/private/NSError+GRPC.h index f4729dc8a13..e0c1efc1f91 100644 --- a/src/objective-c/GRPCClient/private/NSError+GRPC.h +++ b/src/objective-c/GRPCClient/private/NSError+GRPC.h @@ -35,7 +35,9 @@ #include @interface NSError (GRPC) -// Returns nil if the status code is OK. Otherwise, a NSError whose code is one of |GRPCErrorCode| -// and whose domain is |kGRPCErrorDomain|. +/** + * Returns nil if the status code is OK. Otherwise, a NSError whose code is one of |GRPCErrorCode| + * and whose domain is |kGRPCErrorDomain|. + */ + (instancetype)grpc_errorFromStatusCode:(grpc_status_code)statusCode details:(char *)details; @end diff --git a/src/objective-c/ProtoRPC/ProtoMethod.h b/src/objective-c/ProtoRPC/ProtoMethod.h index 8f554a04832..a0ed2cf98a5 100644 --- a/src/objective-c/ProtoRPC/ProtoMethod.h +++ b/src/objective-c/ProtoRPC/ProtoMethod.h @@ -33,8 +33,10 @@ #import -// A fully-qualified proto service method name. Full qualification is needed because a gRPC endpoint -// can implement multiple services. +/** + * A fully-qualified proto service method name. Full qualification is needed because a gRPC endpoint + * can implement multiple services. + */ @interface ProtoMethod : NSObject @property(nonatomic, readonly) NSString *package; @property(nonatomic, readonly) NSString *service; diff --git a/src/objective-c/RxLibrary/GRXBufferedPipe.h b/src/objective-c/RxLibrary/GRXBufferedPipe.h index ca94ce275f7..03b0359278a 100644 --- a/src/objective-c/RxLibrary/GRXBufferedPipe.h +++ b/src/objective-c/RxLibrary/GRXBufferedPipe.h @@ -36,25 +36,27 @@ #import "GRXWriteable.h" #import "GRXWriter.h" -// A buffered pipe is a Writer that also acts as a Writeable. -// Once it is started, whatever values are written into it (via -writeValue:) will be propagated -// immediately, unless flow control prevents it. -// If it is throttled and keeps receiving values, as well as if it receives values before being -// started, it will buffer them and propagate them in order as soon as its state becomes Started. -// If it receives an error (via -writesFinishedWithError:), it will drop any buffered values and -// propagate the error immediately. -// -// Beware that a pipe of this type can't prevent receiving more values when it is paused (for -// example if used to write data to a congested network connection). Because in such situations the -// pipe will keep buffering all data written to it, your application could run out of memory and -// crash. If you want to react to flow control signals to prevent that, instead of using this class -// you can implement an object that conforms to GRXWriter. -// -// Thread-safety: -// The methods of an object of this class should not be called concurrently from different threads. +/** + * A buffered pipe is a Writer that also acts as a Writeable. + * Once it is started, whatever values are written into it (via -writeValue:) will be propagated + * immediately, unless flow control prevents it. + * If it is throttled and keeps receiving values, as well as if it receives values before being + * started, it will buffer them and propagate them in order as soon as its state becomes Started. + * If it receives an error (via -writesFinishedWithError:), it will drop any buffered values and + * propagate the error immediately. + * + * Beware that a pipe of this type can't prevent receiving more values when it is paused (for + * example if used to write data to a congested network connection). Because in such situations the + * pipe will keep buffering all data written to it, your application could run out of memory and + * crash. If you want to react to flow control signals to prevent that, instead of using this class + * you can implement an object that conforms to GRXWriter. + * + * Thread-safety: + * The methods of an object of this class should not be called concurrently from different threads. + */ @interface GRXBufferedPipe : GRXWriter -// Convenience constructor. +/** Convenience constructor. */ + (instancetype)pipe; @end diff --git a/src/objective-c/RxLibrary/GRXConcurrentWriteable.h b/src/objective-c/RxLibrary/GRXConcurrentWriteable.h index 1080001905e..b2775f98b56 100644 --- a/src/objective-c/RxLibrary/GRXConcurrentWriteable.h +++ b/src/objective-c/RxLibrary/GRXConcurrentWriteable.h @@ -36,36 +36,48 @@ #import "GRXWriter.h" #import "GRXWriteable.h" -// This is a thread-safe wrapper over a GRXWriteable instance. It lets one enqueue calls to a -// GRXWriteable instance for the main thread, guaranteeing that writesFinishedWithError: is the last -// message sent to it (no matter what messages are sent to the wrapper, in what order, nor from -// which thread). It also guarantees that, if cancelWithError: is called from the main thread (e.g. -// by the app cancelling the writes), no further messages are sent to the writeable except -// writesFinishedWithError:. -// -// TODO(jcanizales): Let the user specify another queue for the writeable callbacks. +/** + * This is a thread-safe wrapper over a GRXWriteable instance. It lets one enqueue calls to a + * GRXWriteable instance for the main thread, guaranteeing that writesFinishedWithError: is the last + * message sent to it (no matter what messages are sent to the wrapper, in what order, nor from + * which thread). It also guarantees that, if cancelWithError: is called from the main thread (e.g. + * by the app cancelling the writes), no further messages are sent to the writeable except + * writesFinishedWithError:. + * + * TODO(jcanizales): Let the user specify another queue for the writeable callbacks. + */ @interface GRXConcurrentWriteable : NSObject -// The GRXWriteable passed is the wrapped writeable. -// The GRXWriteable instance is retained until writesFinishedWithError: is sent to it, and released -// after that. +/** + * The GRXWriteable passed is the wrapped writeable. + * The GRXWriteable instance is retained until writesFinishedWithError: is sent to it, and released + * after that. + */ - (instancetype)initWithWriteable:(id)writeable NS_DESIGNATED_INITIALIZER; -// Enqueues writeValue: to be sent to the writeable in the main thread. -// The passed handler is invoked from the main thread after writeValue: returns. +/** + * Enqueues writeValue: to be sent to the writeable in the main thread. + * The passed handler is invoked from the main thread after writeValue: returns. + */ - (void)enqueueValue:(id)value completionHandler:(void (^)())handler; -// Enqueues writesFinishedWithError:nil to be sent to the writeable in the main thread. After that -// message is sent to the writeable, all other methods of this object are effectively noops. +/** + * Enqueues writesFinishedWithError:nil to be sent to the writeable in the main thread. After that + * message is sent to the writeable, all other methods of this object are effectively noops. + */ - (void)enqueueSuccessfulCompletion; -// If the writeable has not yet received a writesFinishedWithError: message, this will enqueue one -// to be sent to it in the main thread, and cancel all other pending messages to the writeable -// enqueued by this object (both past and future). -// The error argument cannot be nil. +/** + * If the writeable has not yet received a writesFinishedWithError: message, this will enqueue one + * to be sent to it in the main thread, and cancel all other pending messages to the writeable + * enqueued by this object (both past and future). + * The error argument cannot be nil. + */ - (void)cancelWithError:(NSError *)error; -// Cancels all pending messages to the writeable enqueued by this object (both past and future). -// Because the writeable won't receive writesFinishedWithError:, this also releases the writeable. +/** + * Cancels all pending messages to the writeable enqueued by this object (both past and future). + * Because the writeable won't receive writesFinishedWithError:, this also releases the writeable. + */ - (void)cancelSilently; @end diff --git a/src/objective-c/RxLibrary/GRXForwardingWriter.h b/src/objective-c/RxLibrary/GRXForwardingWriter.h index f310832284a..8d45b8ed8d3 100644 --- a/src/objective-c/RxLibrary/GRXForwardingWriter.h +++ b/src/objective-c/RxLibrary/GRXForwardingWriter.h @@ -33,17 +33,19 @@ #import "GRXWriter.h" -// A "proxy" class that simply forwards values, completion, and errors from its input writer to its -// writeable. -// It is useful as a superclass for pipes that act as a transformation of their -// input writer, and for classes that represent objects with input and -// output sequences of values, like an RPC. -// -// Thread-safety: -// All messages sent to this object need to be serialized. When it is started, the writer it wraps -// is started in the same thread. Manual state changes are propagated to the wrapped writer in the -// same thread too. Importantly, all messages the wrapped writer sends to its writeable need to be -// serialized with any message sent to this object. +/** + * A "proxy" class that simply forwards values, completion, and errors from its input writer to its + * writeable. + * It is useful as a superclass for pipes that act as a transformation of their + * input writer, and for classes that represent objects with input and + * output sequences of values, like an RPC. + * + * Thread-safety: + * All messages sent to this object need to be serialized. When it is started, the writer it wraps + * is started in the same thread. Manual state changes are propagated to the wrapped writer in the + * same thread too. Importantly, all messages the wrapped writer sends to its writeable need to be + * serialized with any message sent to this object. + */ @interface GRXForwardingWriter : GRXWriter - (instancetype)initWithWriter:(GRXWriter *)writer NS_DESIGNATED_INITIALIZER; @end diff --git a/src/objective-c/RxLibrary/GRXImmediateWriter.h b/src/objective-c/RxLibrary/GRXImmediateWriter.h index 3fcc2594342..e22b056ff56 100644 --- a/src/objective-c/RxLibrary/GRXImmediateWriter.h +++ b/src/objective-c/RxLibrary/GRXImmediateWriter.h @@ -35,46 +35,60 @@ #import "GRXWriter.h" -// Utility to construct GRXWriter instances from values that are immediately available when -// required. -// -// Thread-safety: -// -// An object of this class shouldn't be messaged concurrently by more than one thread. It will start -// messaging the writeable before |startWithWriteable:| returns, in the same thread. That is the -// only place where the writer can be paused or stopped prematurely. -// -// If a paused writer of this class is resumed, it will start messaging the writeable, in the same -// thread, before |setState:| returns. Because the object can't be legally accessed concurrently, -// that's the only place where it can be paused again (or stopped). +/** + * Utility to construct GRXWriter instances from values that are immediately available when + * required. + * + * Thread-safety: + * + * An object of this class shouldn't be messaged concurrently by more than one thread. It will start + * messaging the writeable before |startWithWriteable:| returns, in the same thread. That is the + * only place where the writer can be paused or stopped prematurely. + * + * If a paused writer of this class is resumed, it will start messaging the writeable, in the same + * thread, before |setState:| returns. Because the object can't be legally accessed concurrently, + * that's the only place where it can be paused again (or stopped). + */ @interface GRXImmediateWriter : GRXWriter -// Returns a writer that pulls values from the passed NSEnumerator instance and pushes them to -// its writeable. The NSEnumerator is released when it finishes. +/** + * Returns a writer that pulls values from the passed NSEnumerator instance and pushes them to + * its writeable. The NSEnumerator is released when it finishes. + */ + (GRXWriter *)writerWithEnumerator:(NSEnumerator *)enumerator; -// Returns a writer that pushes to its writeable the successive values returned by the passed -// block. When the block first returns nil, it is released. +/** + * Returns a writer that pushes to its writeable the successive values returned by the passed + * block. When the block first returns nil, it is released. + */ + (GRXWriter *)writerWithValueSupplier:(id (^)())block; -// Returns a writer that iterates over the values of the passed container and pushes them to -// its writeable. The container is released when the iteration is over. -// -// Note that the usual speed gain of NSFastEnumeration over NSEnumerator results from not having to -// call one method per element. Because GRXWriteable instances accept values one by one, that speed -// gain doesn't happen here. +/** + * Returns a writer that iterates over the values of the passed container and pushes them to + * its writeable. The container is released when the iteration is over. + * + * Note that the usual speed gain of NSFastEnumeration over NSEnumerator results from not having to + * call one method per element. Because GRXWriteable instances accept values one by one, that speed + * gain doesn't happen here. + */ + (GRXWriter *)writerWithContainer:(id)container; -// Returns a writer that sends the passed value to its writeable and then finishes (releasing the -// value). +/** + * Returns a writer that sends the passed value to its writeable and then finishes (releasing the + * value). + */ + (GRXWriter *)writerWithValue:(id)value; -// Returns a writer that, as part of its start method, sends the passed error to the writeable -// (then releasing the error). +/** + * Returns a writer that, as part of its start method, sends the passed error to the writeable + * (then releasing the error). + */ + (GRXWriter *)writerWithError:(NSError *)error; -// Returns a writer that, as part of its start method, finishes immediately without sending any -// values to its writeable. +/** + * Returns a writer that, as part of its start method, finishes immediately without sending any + * values to its writeable. + */ + (GRXWriter *)emptyWriter; @end diff --git a/src/objective-c/RxLibrary/GRXWriteable.h b/src/objective-c/RxLibrary/GRXWriteable.h index 45613d6dd09..7fe805c6638 100644 --- a/src/objective-c/RxLibrary/GRXWriteable.h +++ b/src/objective-c/RxLibrary/GRXWriteable.h @@ -33,16 +33,20 @@ #import -// A GRXWriteable is an object to which a sequence of values can be sent. The -// sequence finishes with an optional error. +/** + * A GRXWriteable is an object to which a sequence of values can be sent. The + * sequence finishes with an optional error. + */ @protocol GRXWriteable -// Push the next value of the sequence to the receiving object. +/** Push the next value of the sequence to the receiving object. */ - (void)writeValue:(id)value; -// Signal that the sequence is completed, or that an error ocurred. After this -// message is sent to the instance, neither it nor writeValue: may be -// called again. +/** + * Signal that the sequence is completed, or that an error ocurred. After this + * message is sent to the instance, neither it nor writeValue: may be + * called again. + */ - (void)writesFinishedWithError:(NSError *)errorOrNil; @end @@ -51,8 +55,10 @@ typedef void (^GRXCompletionHandler)(NSError *errorOrNil); typedef void (^GRXSingleHandler)(id value, NSError *errorOrNil); typedef void (^GRXEventHandler)(BOOL done, id value, NSError *error); -// Utility to create objects that conform to the GRXWriteable protocol, from -// blocks that handle each of the two methods of the protocol. +/** + * Utility to create objects that conform to the GRXWriteable protocol, from + * blocks that handle each of the two methods of the protocol. + */ @interface GRXWriteable : NSObject + (instancetype)writeableWithSingleHandler:(GRXSingleHandler)handler; diff --git a/src/objective-c/RxLibrary/GRXWriter+Immediate.h b/src/objective-c/RxLibrary/GRXWriter+Immediate.h index b75c0a5a64c..be880151f4f 100644 --- a/src/objective-c/RxLibrary/GRXWriter+Immediate.h +++ b/src/objective-c/RxLibrary/GRXWriter+Immediate.h @@ -35,32 +35,44 @@ @interface GRXWriter (Immediate) -// Returns a writer that pulls values from the passed NSEnumerator instance and pushes them to -// its writeable. The NSEnumerator is released when it finishes. +/** + * Returns a writer that pulls values from the passed NSEnumerator instance and pushes them to + * its writeable. The NSEnumerator is released when it finishes. + */ + (instancetype)writerWithEnumerator:(NSEnumerator *)enumerator; -// Returns a writer that pushes to its writeable the successive values returned by the passed -// block. When the block first returns nil, it is released. +/** + * Returns a writer that pushes to its writeable the successive values returned by the passed + * block. When the block first returns nil, it is released. + */ + (instancetype)writerWithValueSupplier:(id (^)())block; -// Returns a writer that iterates over the values of the passed container and pushes them to -// its writeable. The container is released when the iteration is over. -// -// Note that the usual speed gain of NSFastEnumeration over NSEnumerator results from not having to -// call one method per element. Because GRXWriteable instances accept values one by one, that speed -// gain doesn't happen here. +/** + * Returns a writer that iterates over the values of the passed container and pushes them to + * its writeable. The container is released when the iteration is over. + * + * Note that the usual speed gain of NSFastEnumeration over NSEnumerator results from not having to + * call one method per element. Because GRXWriteable instances accept values one by one, that speed + * gain doesn't happen here. + */ + (instancetype)writerWithContainer:(id)container; -// Returns a writer that sends the passed value to its writeable and then finishes (releasing the -// value). +/** + * Returns a writer that sends the passed value to its writeable and then finishes (releasing the + * value). + */ + (instancetype)writerWithValue:(id)value; -// Returns a writer that, as part of its start method, sends the passed error to the writeable -// (then releasing the error). +/** + * Returns a writer that, as part of its start method, sends the passed error to the writeable + * (then releasing the error). + */ + (instancetype)writerWithError:(NSError *)error; -// Returns a writer that, as part of its start method, finishes immediately without sending any -// values to its writeable. +/** + * Returns a writer that, as part of its start method, finishes immediately without sending any + * values to its writeable. + */ + (instancetype)emptyWriter; @end diff --git a/src/objective-c/RxLibrary/GRXWriter+Transformations.h b/src/objective-c/RxLibrary/GRXWriter+Transformations.h index 60c4da37d69..17d61e75410 100644 --- a/src/objective-c/RxLibrary/GRXWriter+Transformations.h +++ b/src/objective-c/RxLibrary/GRXWriter+Transformations.h @@ -35,8 +35,10 @@ @interface GRXWriter (Transformations) -// Returns a writer that wraps the receiver, and has all the values the receiver would write -// transformed by the provided mapping function. +/** + * Returns a writer that wraps the receiver, and has all the values the receiver would write + * transformed by the provided mapping function. + */ - (GRXWriter *)map:(id (^)(id value))map; @end diff --git a/src/objective-c/RxLibrary/GRXWriter.h b/src/objective-c/RxLibrary/GRXWriter.h index b1c994aa382..ff81268446a 100644 --- a/src/objective-c/RxLibrary/GRXWriter.h +++ b/src/objective-c/RxLibrary/GRXWriter.h @@ -35,73 +35,87 @@ #import "GRXWriteable.h" -// States of a writer. +/** States of a writer. */ typedef NS_ENUM(NSInteger, GRXWriterState) { - // The writer has not yet been given a writeable to which it can push its values. To have a writer - // transition to the Started state, send it a startWithWriteable: message. - // - // A writer's state cannot be manually set to this value. + /** + * The writer has not yet been given a writeable to which it can push its values. To have a writer + * transition to the Started state, send it a startWithWriteable: message. + * + * A writer's state cannot be manually set to this value. + */ GRXWriterStateNotStarted, - // The writer might push values to the writeable at any moment. + /** The writer might push values to the writeable at any moment. */ GRXWriterStateStarted, - // The writer is temporarily paused, and won't send any more values to the writeable unless its - // state is set back to Started. The writer might still transition to the Finished state at any - // moment, and is allowed to send writesFinishedWithError: to its writeable. + /** + * The writer is temporarily paused, and won't send any more values to the writeable unless its + * state is set back to Started. The writer might still transition to the Finished state at any + * moment, and is allowed to send writesFinishedWithError: to its writeable. + */ GRXWriterStatePaused, - // The writer has released its writeable and won't interact with it anymore. - // - // One seldomly wants to set a writer's state to this value, as its writeable isn't notified with - // a writesFinishedWithError: message. Instead, sending finishWithError: to the writer will make - // it notify the writeable and then transition to this state. + /** + * The writer has released its writeable and won't interact with it anymore. + * + * One seldomly wants to set a writer's state to this value, as its writeable isn't notified with + * a writesFinishedWithError: message. Instead, sending finishWithError: to the writer will make + * it notify the writeable and then transition to this state. + */ GRXWriterStateFinished }; -// An GRXWriter object can produce, on demand, a sequence of values. The sequence may be produced -// asynchronously, and it may consist of any number of elements, including none or an infinite -// number. -// -// GRXWriter is the active dual of NSEnumerator. The difference between them is thus whether the -// object plays an active or passive role during usage: A user of NSEnumerator pulls values off it, -// and passes the values to a writeable. A user of GRXWriter, though, just gives it a writeable, and -// the GRXWriter instance pushes values to the writeable. This makes this protocol suitable to -// represent a sequence of future values, as well as collections with internal iteration. -// -// An instance of GRXWriter can start producing values after a writeable is passed to it. It can -// also be commanded to finish the sequence immediately (with an optional error). Finally, it can be -// asked to pause, and resumed later. All GRXWriter objects support pausing and early termination. -// -// Thread-safety: -// -// State transitions take immediate effect if the object is used from a single thread. Subclasses -// might offer stronger guarantees. -// -// Unless otherwise indicated by a conforming subclass, no messages should be sent concurrently to a -// GRXWriter. I.e., conforming classes aren't required to be thread-safe. +/** + * An GRXWriter object can produce, on demand, a sequence of values. The sequence may be produced + * asynchronously, and it may consist of any number of elements, including none or an infinite + * number. + * + * GRXWriter is the active dual of NSEnumerator. The difference between them is thus whether the + * object plays an active or passive role during usage: A user of NSEnumerator pulls values off it, + * and passes the values to a writeable. A user of GRXWriter, though, just gives it a writeable, and + * the GRXWriter instance pushes values to the writeable. This makes this protocol suitable to + * represent a sequence of future values, as well as collections with internal iteration. + * + * An instance of GRXWriter can start producing values after a writeable is passed to it. It can + * also be commanded to finish the sequence immediately (with an optional error). Finally, it can be + * asked to pause, and resumed later. All GRXWriter objects support pausing and early termination. + * + * Thread-safety: + * + * State transitions take immediate effect if the object is used from a single thread. Subclasses + * might offer stronger guarantees. + * + * Unless otherwise indicated by a conforming subclass, no messages should be sent concurrently to a + * GRXWriter. I.e., conforming classes aren't required to be thread-safe. + */ @interface GRXWriter : NSObject -// This property can be used to query the current state of the writer, which determines how it might -// currently use its writeable. Some state transitions can be triggered by setting this property to -// the corresponding value, and that's useful for advanced use cases like pausing an writer. For -// more details, see the documentation of the enum further down. +/** + * This property can be used to query the current state of the writer, which determines how it might + * currently use its writeable. Some state transitions can be triggered by setting this property to + * the corresponding value, and that's useful for advanced use cases like pausing an writer. For + * more details, see the documentation of the enum further down. + */ @property(nonatomic) GRXWriterState state; -// Transition to the Started state, and start sending messages to the writeable (a reference to it -// is retained). Messages to the writeable may be sent before the method returns, or they may be -// sent later in the future. See GRXWriteable.h for the different messages a writeable can receive. -// -// If this writer draws its values from an external source (e.g. from the filesystem or from a -// server), calling this method will commonly trigger side effects (like network connections). -// -// This method might only be called on writers in the NotStarted state. +/** + * Transition to the Started state, and start sending messages to the writeable (a reference to it + * is retained). Messages to the writeable may be sent before the method returns, or they may be + * sent later in the future. See GRXWriteable.h for the different messages a writeable can receive. + * + * If this writer draws its values from an external source (e.g. from the filesystem or from a + * server), calling this method will commonly trigger side effects (like network connections). + * + * This method might only be called on writers in the NotStarted state. + */ - (void)startWithWriteable:(id)writeable; -// Send writesFinishedWithError:errorOrNil to the writeable. Then release the reference to it and -// transition to the Finished state. -// -// This method might only be called on writers in the Started or Paused state. +/** + * Send writesFinishedWithError:errorOrNil to the writeable. Then release the reference to it and + * transition to the Finished state. + * + * This method might only be called on writers in the Started or Paused state. + */ - (void)finishWithError:(NSError *)errorOrNil; @end diff --git a/src/objective-c/RxLibrary/NSEnumerator+GRXUtil.h b/src/objective-c/RxLibrary/NSEnumerator+GRXUtil.h index 400e834c6ae..0622f7067c0 100644 --- a/src/objective-c/RxLibrary/NSEnumerator+GRXUtil.h +++ b/src/objective-c/RxLibrary/NSEnumerator+GRXUtil.h @@ -35,17 +35,23 @@ @interface NSEnumerator (GRXUtil) -// Returns a NSEnumerator instance that iterates through the elements of the passed container that -// supports fast enumeration. Note that this negates the speed benefits of fast enumeration over -// NSEnumerator. It's only intended for the rare cases when one needs the latter and only has the -// former, e.g. for iteration that needs to be paused and resumed later. +/** + * Returns a NSEnumerator instance that iterates through the elements of the passed container that + * supports fast enumeration. Note that this negates the speed benefits of fast enumeration over + * NSEnumerator. It's only intended for the rare cases when one needs the latter and only has the + * former, e.g. for iteration that needs to be paused and resumed later. + */ + (NSEnumerator *)grx_enumeratorWithContainer:(id)container; -// Returns a NSEnumerator instance that provides a single object before finishing. The value is then -// released. +/** + * Returns a NSEnumerator instance that provides a single object before finishing. The value is then + * released. + */ + (NSEnumerator *)grx_enumeratorWithSingleValue:(id)value; -// Returns a NSEnumerator instance that delegates the invocations of nextObject to the passed block. -// When the block first returns nil, it is released. +/** + * Returns a NSEnumerator instance that delegates the invocations of nextObject to the passed block. + * When the block first returns nil, it is released. + */ + (NSEnumerator *)grx_enumeratorWithValueSupplier:(id (^)())block; @end diff --git a/src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h b/src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h index 34cfc4d8a77..fb50c37863a 100644 --- a/src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h +++ b/src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h @@ -33,10 +33,14 @@ #import -// Concrete subclass of NSEnumerator that delegates the invocations of nextObject to a block passed -// on initialization. +/** + * Concrete subclass of NSEnumerator that delegates the invocations of nextObject to a block passed + * on initialization. + */ @interface GRXNSBlockEnumerator : NSEnumerator -// The first time the passed block returns nil, the enumeration will end and the block will be -// released. +/** + * The first time the passed block returns nil, the enumeration will end and the block will be + * released. + */ - (instancetype)initWithValueSupplier:(id (^)())block; @end diff --git a/src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h b/src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h index 15650292055..62c27dbc7f3 100644 --- a/src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h +++ b/src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h @@ -33,11 +33,15 @@ #import -// This is a bridge to interact through NSEnumerator's interface with objects that only conform to -// NSFastEnumeration. (There's nothing specifically fast about it - you certainly don't win any -// speed by using this instead of a NSEnumerator provided by your container). +/** + * This is a bridge to interact through NSEnumerator's interface with objects that only conform to + * NSFastEnumeration. (There's nothing specifically fast about it - you certainly don't win any + * speed by using this instead of a NSEnumerator provided by your container). + */ @interface GRXNSFastEnumerator : NSEnumerator -// After the iteration of the container (via the NSFastEnumeration protocol) is over, the container -// is released. If the container is modified during enumeration, an exception is thrown. +/** + * After the iteration of the container (via the NSFastEnumeration protocol) is over, the container + * is released. If the container is modified during enumeration, an exception is thrown. + */ - (instancetype)initWithContainer:(id)container; @end diff --git a/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h b/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h index 12aa51e2139..24a21a1b22c 100644 --- a/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h +++ b/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h @@ -33,9 +33,11 @@ #import -// Concrete subclass of NSEnumerator whose instances return a single object before finishing. +/** Concrete subclass of NSEnumerator whose instances return a single object before finishing. */ @interface GRXNSScalarEnumerator : NSEnumerator -// Param value: the single object this instance will produce. After the first invocation of -// nextObject, the value is released. +/** + * Param value: the single object this instance will produce. After the first invocation of + * nextObject, the value is released. + */ - (instancetype)initWithValue:(id)value; @end diff --git a/src/objective-c/RxLibrary/transformations/GRXMappingWriter.h b/src/objective-c/RxLibrary/transformations/GRXMappingWriter.h index 43b87068647..01a15e2a430 100644 --- a/src/objective-c/RxLibrary/transformations/GRXMappingWriter.h +++ b/src/objective-c/RxLibrary/transformations/GRXMappingWriter.h @@ -33,7 +33,7 @@ #import "RxLibrary/GRXForwardingWriter.h" -// A "proxy" writer that transforms all the values of its input writer by using a mapping function. +/** A "proxy" writer that transforms all the values of its input writer by using a mapping function. */ @interface GRXMappingWriter : GRXForwardingWriter - (instancetype)initWithWriter:(GRXWriter *)writer map:(id (^)(id value))map NS_DESIGNATED_INITIALIZER;