Merge pull request #3961 from jcanizales/cocoadocs-format

Format ObjC comment docs as Cocoadocs

src/objective-c/GRPCClient/GRPCCall+OAuth2.h

@@ -33,17 +33,19 @@
 
 #import "GRPCCall.h"
 
-// Helpers for setting and reading headers compatible with OAuth2.
+/** Helpers for setting and reading headers compatible with OAuth2. */
 @interface GRPCCall (OAuth2)
 
-// Setting this property is equivalent to setting "Bearer <passed token>" as the value of the
-// request header with key "authorization" (the authorization header). Setting it to nil removes the
-// authorization header from the request.
-// The value obtained by getting the property is the OAuth2 bearer token if the authorization header
-// of the request has the form "Bearer <token>", or nil otherwise.
+/**
+ * Setting this property is equivalent to setting "Bearer <passed token>" as the value of the
+ * request header with key "authorization" (the authorization header). Setting it to nil removes the
+ * authorization header from the request.
+ * The value obtained by getting the property is the OAuth2 bearer token if the authorization header
+ * of the request has the form "Bearer <token>", or nil otherwise.
+ */
 @property(atomic, copy) NSString *oauth2AccessToken;
 
-// Returns the value (if any) of the "www-authenticate" response header (the challenge header).
+/** Returns the value (if any) of the "www-authenticate" response header (the challenge header). */
 @property(atomic, readonly) NSString *oauth2ChallengeHeader;
 
 @end

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

src/objective-c/GRPCClient/GRPCCall.h

@@ -31,117 +31,145 @@
  *
  */
 
-// The gRPC protocol is an RPC protocol on top of HTTP2.
-//
-// While the most common type of RPC receives only one request message and returns only one response
-// message, the protocol also supports RPCs that return multiple individual messages in a streaming
-// fashion, RPCs that accept a stream of request messages, or RPCs with both streaming requests and
-// responses.
-//
-// Conceptually, each gRPC call consists of a bidirectional stream of binary messages, with RPCs of
-// the "non-streaming type" sending only one message in the corresponding direction (the protocol
-// doesn't make any distinction).
-//
-// Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs can be multiplexed
-// transparently on the same TCP connection.
+/**
+ * The gRPC protocol is an RPC protocol on top of HTTP2.
+ *
+ * While the most common type of RPC receives only one request message and returns only one response
+ * message, the protocol also supports RPCs that return multiple individual messages in a streaming
+ * fashion, RPCs that accept a stream of request messages, or RPCs with both streaming requests and
+ * responses.
+ *
+ * Conceptually, each gRPC call consists of a bidirectional stream of binary messages, with RPCs of
+ * the "non-streaming type" sending only one message in the corresponding direction (the protocol
+ * doesn't make any distinction).
+ *
+ * Each RPC uses a different HTTP2 stream, and thus multiple simultaneous RPCs can be multiplexed
+ * transparently on the same TCP connection.
+ */
 
 #import <Foundation/Foundation.h>
 #import <RxLibrary/GRXWriter.h>
 
 #pragma mark gRPC errors
 
-// Domain of NSError objects produced by gRPC.
+/** Domain of NSError objects produced by gRPC. */
 extern NSString *const kGRPCErrorDomain;
 
-// gRPC error codes.
-// Note that a few of these are never produced by the gRPC libraries, but are of general utility for
-// server applications to produce.
+/**
+ * gRPC error codes.
+ * Note that a few of these are never produced by the gRPC libraries, but are of general utility for
+ * 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,
 
-  // Unknown error. Errors raised by APIs that do not return enough error information may be
-  // converted to this error.
+  /**
+   * Unknown error. Errors raised by APIs that do not return enough error information may be
+   * converted to this error.
+   */
   GRPCErrorCodeUnknown = 2,
 
-  // The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION.
-  // INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the
-  // server (e.g., a malformed file name).
+  /**
+   * The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION.
+   * INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the
+   * server (e.g., a malformed file name).
+   */
   GRPCErrorCodeInvalidArgument = 3,
 
-  // Deadline expired before operation could complete. For operations that change the state of the
-  // server, this error may be returned even if the operation has completed successfully. For
-  // example, a successful response from the server could have been delayed long enough for the
-  // deadline to expire.
+  /**
+   * Deadline expired before operation could complete. For operations that change the state of the
+   * server, this error may be returned even if the operation has completed successfully. For
+   * example, a successful response from the server could have been delayed long enough for the
+   * deadline to expire.
+   */
   GRPCErrorCodeDeadlineExceeded = 4,
 
-  // Some requested entity (e.g., file or directory) was not found.
+  /** Some requested entity (e.g., file or directory) was not found. */
   GRPCErrorCodeNotFound = 5,
 
-  // Some entity that we attempted to create (e.g., file or directory) already exists.
+  /** Some entity that we attempted to create (e.g., file or directory) already exists. */
   GRPCErrorCodeAlreadyExists = 6,
 
-  // The caller does not have permission to execute the specified operation. PERMISSION_DENIED isn't
-  // used for rejections caused by exhausting some resource (RESOURCE_EXHAUSTED is used instead for
-  // those errors). PERMISSION_DENIED doesn't indicate a failure to identify the caller
-  // (UNAUTHENTICATED is used instead for those errors).
+  /**
+   * The caller does not have permission to execute the specified operation. PERMISSION_DENIED isn't
+   * used for rejections caused by exhausting some resource (RESOURCE_EXHAUSTED is used instead for
+   * those errors). PERMISSION_DENIED doesn't indicate a failure to identify the caller
+   * (UNAUTHENTICATED is used instead for those errors).
+   */
   GRPCErrorCodePermissionDenied = 7,
 
-  // The request does not have valid authentication credentials for the operation (e.g. the caller's
-  // identity can't be verified).
+  /**
+   * The request does not have valid authentication credentials for the operation (e.g. the caller's
+   * identity can't be verified).
+   */
   GRPCErrorCodeUnauthenticated = 16,
 
-  // Some resource has been exhausted, perhaps a per-user quota.
+  /** Some resource has been exhausted, perhaps a per-user quota. */
   GRPCErrorCodeResourceExhausted = 8,
 
-  // The RPC was rejected because the server is not in a state required for the procedure's
-  // execution. For example, a directory to be deleted may be non-empty, etc.
-  // The client should not retry until the server state has been explicitly fixed (e.g. by
-  // performing another RPC). The details depend on the service being called, and should be found in
-  // the NSError's userInfo.
+  /**
+   * The RPC was rejected because the server is not in a state required for the procedure's
+   * execution. For example, a directory to be deleted may be non-empty, etc.
+   * The client should not retry until the server state has been explicitly fixed (e.g. by
+   * performing another RPC). The details depend on the service being called, and should be found in
+   * the NSError's userInfo.
+   */
   GRPCErrorCodeFailedPrecondition = 9,
 
-  // The RPC was aborted, typically due to a concurrency issue like sequencer check failures,
-  // transaction aborts, etc. The client should retry at a higher-level (e.g., restarting a read-
-  // modify-write sequence).
+  /**
+   * The RPC was aborted, typically due to a concurrency issue like sequencer check failures,
+   * transaction aborts, etc. The client should retry at a higher-level (e.g., restarting a read-
+   * modify-write sequence).
+   */
   GRPCErrorCodeAborted = 10,
 
-  // The RPC was attempted past the valid range. E.g., enumerating past the end of a list.
-  // Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state
-  // changes. For example, an RPC to get elements of a list will generate INVALID_ARGUMENT if asked
-  // to return the element at a negative index, but it will generate OUT_OF_RANGE if asked to return
-  // the element at an index past the current size of the list.
+  /**
+   * The RPC was attempted past the valid range. E.g., enumerating past the end of a list.
+   * Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state
+   * changes. For example, an RPC to get elements of a list will generate INVALID_ARGUMENT if asked
+   * to return the element at a negative index, but it will generate OUT_OF_RANGE if asked to return
+   * the element at an index past the current size of the list.
+   */
   GRPCErrorCodeOutOfRange = 11,
 
-  // The procedure is not implemented or not supported/enabled in this server.
+  /** The procedure is not implemented or not supported/enabled in this server. */
   GRPCErrorCodeUnimplemented = 12,
 
-  // Internal error. Means some invariant expected by the server application or the gRPC library has
-  // been broken.
+  /**
+   * Internal error. Means some invariant expected by the server application or the gRPC library has
+   * been broken.
+   */
   GRPCErrorCodeInternal = 13,
 
-  // The server is currently unavailable. This is most likely a transient condition and may be
-  // corrected by retrying with a backoff.
+  /**
+   * The server is currently unavailable. This is most likely a transient condition and may be
+   * corrected by retrying with a backoff.
+   */
   GRPCErrorCodeUnavailable = 14,
 
-  // Unrecoverable data loss or corruption.
+  /** Unrecoverable data loss or corruption. */
   GRPCErrorCodeDataLoss = 15,
 };
 
-// Keys used in |NSError|'s |userInfo| dictionary to store the response headers and trailers sent by
-// the server.
+/**
+ * Keys used in |NSError|'s |userInfo| dictionary to store the response headers and trailers sent by
+ * the server.
+ */
 extern id const kGRPCHeadersKey;
 extern id const kGRPCTrailersKey;
 
 #pragma mark GRPCCall
 
-// The container of the request headers of an RPC conforms to this protocol, which is a subset of
-// NSMutableDictionary's interface. It will become a NSMutableDictionary later on.
-// The keys of this container are the header names, which per the HTTP standard are case-
-// insensitive. They are stored in lowercase (which is how HTTP/2 mandates them on the wire), and
-// can only consist of ASCII characters.
-// A header value is a NSString object (with only ASCII characters), unless the header name has the
-// suffix "-bin", in which case the value has to be a NSData object.
+/**
+ * The container of the request headers of an RPC conforms to this protocol, which is a subset of
+ * NSMutableDictionary's interface. It will become a NSMutableDictionary later on.
+ * The keys of this container are the header names, which per the HTTP standard are case-
+ * insensitive. They are stored in lowercase (which is how HTTP/2 mandates them on the wire), and
+ * can only consist of ASCII characters.
+ * A header value is a NSString object (with only ASCII characters), unless the header name has the
+ * suffix "-bin", in which case the value has to be a NSData object.
+ */
 @protocol GRPCRequestHeaders <NSObject>
 
 @property(nonatomic, readonly) NSUInteger count;
@@ -154,53 +182,63 @@ extern id const kGRPCTrailersKey;
 
 @end
 
-// Represents a single gRPC remote call.
+/** Represents a single gRPC remote call. */
 @interface GRPCCall : GRXWriter
 
-// These HTTP headers will be passed to the server as part of this call. Each HTTP header is a
-// name-value pair with string names and either string or binary values.
-//
-// The passed dictionary has to use NSString keys, corresponding to the header names. The value
-// associated to each can be a NSString object or a NSData object. E.g.:
-//
-// call.requestHeaders = @{@"authorization": @"Bearer ..."};
-//
-// call.requestHeaders[@"my-header-bin"] = someData;
-//
-// After the call is started, trying to modify this property is an error.
-//
-// The property is initialized to an empty NSMutableDictionary.
+/**
+ * These HTTP headers will be passed to the server as part of this call. Each HTTP header is a
+ * name-value pair with string names and either string or binary values.
+ *
+ * The passed dictionary has to use NSString keys, corresponding to the header names. The value
+ * associated to each can be a NSString object or a NSData object. E.g.:
+ *
+ * call.requestHeaders = @{@"authorization": @"Bearer ..."};
+ *
+ * call.requestHeaders[@"my-header-bin"] = someData;
+ *
+ * After the call is started, trying to modify this property is an error.
+ *
+ * The property is initialized to an empty NSMutableDictionary.
+ */
 @property(atomic, readonly) id<GRPCRequestHeaders> requestHeaders;
 
-// This dictionary is populated with the HTTP headers received from the server. This happens before
-// any response message is received from the server. It has the same structure as the request
-// headers dictionary: Keys are NSString header names; names ending with the suffix "-bin" have a
-// NSData value; the others have a NSString value.
-//
-// The value of this property is nil until all response headers are received, and will change before
-// any of -writeValue: or -writesFinishedWithError: are sent to the writeable.
+/**
+ * This dictionary is populated with the HTTP headers received from the server. This happens before
+ * any response message is received from the server. It has the same structure as the request
+ * headers dictionary: Keys are NSString header names; names ending with the suffix "-bin" have a
+ * NSData value; the others have a NSString value.
+ *
+ * The value of this property is nil until all response headers are received, and will change before
+ * any of -writeValue: or -writesFinishedWithError: are sent to the writeable.
+ */
 @property(atomic, readonly) NSDictionary *responseHeaders;
 
-// Same as responseHeaders, but populated with the HTTP trailers received from the server before the
-// call finishes.
-//
-// The value of this property is nil until all response trailers are received, and will change
-// before -writesFinishedWithError: is sent to the writeable.
+/**
+ * Same as responseHeaders, but populated with the HTTP trailers received from the server before the
+ * call finishes.
+ *
+ * The value of this property is nil until all response trailers are received, and will change
+ * before -writesFinishedWithError: is sent to the writeable.
+ */
 @property(atomic, readonly) NSDictionary *responseTrailers;
 
-// The request writer has to write NSData objects into the provided Writeable. The server will
-// receive each of those separately and in order as distinct messages.
-// A gRPC call might not complete until the request writer finishes. On the other hand, the request
-// finishing doesn't necessarily make the call to finish, as the server might continue sending
-// messages to the response side of the call indefinitely (depending on the semantics of the
-// specific remote method called).
-// To finish a call right away, invoke cancel.
+/**
+ * The request writer has to write NSData objects into the provided Writeable. The server will
+ * receive each of those separately and in order as distinct messages.
+ * A gRPC call might not complete until the request writer finishes. On the other hand, the request
+ * finishing doesn't necessarily make the call to finish, as the server might continue sending
+ * messages to the response side of the call indefinitely (depending on the semantics of the
+ * specific remote method called).
+ * To finish a call right away, invoke cancel.
+ */
 - (instancetype)initWithHost:(NSString *)host
                         path:(NSString *)path
               requestsWriter:(GRXWriter *)requestsWriter NS_DESIGNATED_INITIALIZER;
 
-// Finishes the request side of this call, notifies the server that the RPC should be cancelled, and
-// finishes the response side of the call with an error of code CANCELED.
+/**
+ * Finishes the request side of this call, notifies the server that the RPC should be cancelled, and
+ * finishes the response side of the call with an error of code CANCELED.
+ */
 - (void)cancel;
 
 // TODO(jcanizales): Let specify a deadline. As a category of GRXWriter?

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

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;
 

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;
 

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;

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
 

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

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;

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

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

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

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

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;

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

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

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

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

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

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

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

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;

src/objective-c/change-comments.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python2.7
+# Copyright 2015, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""Change comments style of source files from // to /** */"""
+
+import re
+import sys
+
+
+if len(sys.argv) < 2:
+  print("Please provide at least one source file name as argument.")
+  sys.exit()
+
+for file_name in sys.argv[1:]:
+
+  print("Modifying format of {file} comments in place...".format(
+      file=file_name,
+  ))
+
+
+  # Input
+
+  with open(file_name, "r") as input_file:
+    lines = input_file.readlines()
+
+  def peek():
+    return lines[0]
+
+  def read_line():
+    return lines.pop(0)
+
+  def more_input_available():
+    return lines
+
+
+  # Output
+
+  output_lines = []
+
+  def write(line):
+    output_lines.append(line)
+
+  def flush_output():
+    with open(file_name, "w") as output_file:
+      for line in output_lines:
+        output_file.write(line)
+
+
+  # Pattern matching
+
+  comment_regex = r'^(\s*)//\s(.*)$'
+
+  def is_comment(line):
+    return re.search(comment_regex, line)
+
+  def isnt_comment(line):
+    return not is_comment(line)
+
+  def next_line(predicate):
+    return more_input_available() and predicate(peek())
+
+
+  # Transformation
+
+  def indentation_of(line):
+    match = re.search(comment_regex, line)
+    return match.group(1)
+
+  def content(line):
+    match = re.search(comment_regex, line)
+    return match.group(2)
+
+  def format_as_block(comment_block):
+    if len(comment_block) == 0:
+      return []
+
+    indent = indentation_of(comment_block[0])
+
+    if len(comment_block) == 1:
+      return [indent + "/** " + content(comment_block[0]) + " */\n"]
+
+    block = ["/**"] + [" * " + content(line) for line in comment_block] + [" */"]
+    return [indent + line.rstrip() + "\n" for line in block]
+
+
+  # Main algorithm
+
+  while more_input_available():
+    while next_line(isnt_comment):
+      write(read_line())
+
+    comment_block = []
+    # Get all lines in the same comment block. We could restrict the indentation
+    # to be the same as the first line of the block, but it's probably ok.
+    while (next_line(is_comment)):
+      comment_block.append(read_line())
+
+    for line in format_as_block(comment_block):
+      write(line)
+
+  flush_output()

src/objective-c/format-all-comments.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Copyright 2015, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+find . -type f -name "*.h" ! -path "*/Pods/*" ! -path "./generated_libraries/*" ! -path "./examples/*" ! -path "./tests/*" | xargs ./change-comments.py