Reformat comments as Cocoadocs

22 files changed, 309 insertions, 211 deletions

diff --git a/src/objective-c/GRPCClient/GRPCCall+Tests.h b/src/objective-c/GRPCClient/GRPCCall+Tests.h
index cca1614606..ccc5723ec7 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 86f4149c43..91f2942c98 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 2a7b701576..e2d19d506a 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 ab8d714d22..fe3b8f39d1 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 f0bbd53023..6b4f98746d 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 74257eb058..4e0881e5a2 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 4ca2766147..7747aa53ef 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 f4729dc8a1..e0c1efc1f9 100644
--- a/src/objective-c/GRPCClient/private/NSError+GRPC.h
+++ b/src/objective-c/GRPCClient/private/NSError+GRPC.h
@@ -35,7 +35,9 @@
 #include <grpc/grpc.h>
 
 @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 8f554a0483..a0ed2cf98a 100644
--- a/src/objective-c/ProtoRPC/ProtoMethod.h
+++ b/src/objective-c/ProtoRPC/ProtoMethod.h
@@ -33,8 +33,10 @@
 
 #import <Foundation/Foundation.h>
 
-// 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 ca94ce275f..03b0359278 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<GRXWriteable>
 
-// Convenience constructor.
+/** Convenience constructor. */
 + (instancetype)pipe;
 
 @end
diff --git a/src/objective-c/RxLibrary/GRXConcurrentWriteable.h b/src/objective-c/RxLibrary/GRXConcurrentWriteable.h
index 1080001905..b2775f98b5 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<GRXWriteable>)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 f310832284..8d45b8ed8d 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 3fcc259434..e22b056ff5 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<NSFastEnumeration>)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 45613d6dd0..7fe805c663 100644
--- a/src/objective-c/RxLibrary/GRXWriteable.h
+++ b/src/objective-c/RxLibrary/GRXWriteable.h
@@ -33,16 +33,20 @@
 
 #import <Foundation/Foundation.h>
 
-// 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 <NSObject>
 
-// 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<GRXWriteable>
 
 + (instancetype)writeableWithSingleHandler:(GRXSingleHandler)handler;
diff --git a/src/objective-c/RxLibrary/GRXWriter+Immediate.h b/src/objective-c/RxLibrary/GRXWriter+Immediate.h
index b75c0a5a64..be880151f4 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<NSFastEnumeration>)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 60c4da37d6..17d61e7541 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 b1c994aa38..ff81268446 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<GRXWriteable>)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 400e834c6a..0622f7067c 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<NSFastEnumeration>)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 34cfc4d8a7..fb50c37863 100644
--- a/src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h
+++ b/src/objective-c/RxLibrary/private/GRXNSBlockEnumerator.h
@@ -33,10 +33,14 @@
 
 #import <Foundation/Foundation.h>
 
-// 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 1565029205..62c27dbc7f 100644
--- a/src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h
+++ b/src/objective-c/RxLibrary/private/GRXNSFastEnumerator.h
@@ -33,11 +33,15 @@
 
 #import <Foundation/Foundation.h>
 
-// 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<NSFastEnumeration>)container;
 @end
diff --git a/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h b/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h
index 12aa51e213..24a21a1b22 100644
--- a/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h
+++ b/src/objective-c/RxLibrary/private/GRXNSScalarEnumerator.h
@@ -33,9 +33,11 @@
 
 #import <Foundation/Foundation.h>
 
-// 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 43b8706864..01a15e2a43 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;