Fix documentation of tests

5 files changed, 38 insertions, 26 deletions

diff --git a/src/objective-c/tests/GRPCClientTests.m b/src/objective-c/tests/GRPCClientTests.m
index 09a55e0704..00c4b8830d 100644
--- a/src/objective-c/tests/GRPCClientTests.m
+++ b/src/objective-c/tests/GRPCClientTests.m
@@ -42,9 +42,6 @@
 #import <RxLibrary/GRXWriteable.h>
 #import <RxLibrary/GRXWriter+Immediate.h>
 
-// These are a few tests similar to InteropTests, but which use the generic gRPC client (GRPCCall)
-// rather than a generated proto library on top of it.
-
 static NSString * const kHostAddress = @"localhost:5050";
 static NSString * const kPackage = @"grpc.testing";
 static NSString * const kService = @"TestService";
@@ -53,11 +50,10 @@ static ProtoMethod *kInexistentMethod;
 static ProtoMethod *kEmptyCallMethod;
 static ProtoMethod *kUnaryCallMethod;
 
-// This is an observer class for testing that responseMetadata is KVO-compliant
-
+/** Observer class for testing that responseMetadata is KVO-compliant */
 @interface PassthroughObserver : NSObject
-
-- (instancetype) initWithCallback:(void (^)(NSString*, id, NSDictionary*))callback;
+- (instancetype) initWithCallback:(void (^)(NSString*, id, NSDictionary*))callback
+    NS_DESIGNATED_INITIALIZER;
 
 - (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change
                        context:(void *)context;
@@ -67,23 +63,38 @@ static ProtoMethod *kUnaryCallMethod;
   void (^_callback)(NSString*, id, NSDictionary*);
 }
 
+- (instancetype)init {
+  return [self initWithCallback:nil];
+}
+
 - (instancetype)initWithCallback:(void (^)(NSString *, id, NSDictionary *))callback {
-  self = [super init];
-  if (self) {
+  if (!callback) {
+    return nil;
+  }
+  if ((self = [super init])) {
     _callback = callback;
   }
   return self;
-  
 }
 
-- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context
-{
+- (void)observeValueForKeyPath:(NSString *)keyPath
+                      ofObject:(id)object
+                        change:(NSDictionary *)change
+                       context:(void *)context {
   _callback(keyPath, object, change);
   [object removeObserver:self forKeyPath:keyPath];
 }
 
 @end
 
+# pragma mark Tests
+
+/**
+ * A few tests similar to InteropTests, but which use the generic gRPC client (GRPCCall) rather than
+ * a generated proto library on top of it. Its RPCs are sent to a local cleartext server.
+ *
+ * TODO(jcanizales): Run them also against a local SSL server and against a remote server.
+ */
 @interface GRPCClientTests : XCTestCase
 @end
 
@@ -180,6 +191,7 @@ static ProtoMethod *kUnaryCallMethod;
   [self waitForExpectationsWithTimeout:8 handler:nil];
 }
 
+// TODO(jcanizales): Activate this test against the remote server.
 - (void)testMetadata {
   __weak XCTestExpectation *expectation = [self expectationWithDescription:@"RPC unauthorized."];
 
diff --git a/src/objective-c/tests/InteropTests.h b/src/objective-c/tests/InteropTests.h
index 383e3befb4..6d54343b13 100644
--- a/src/objective-c/tests/InteropTests.h
+++ b/src/objective-c/tests/InteropTests.h
@@ -33,11 +33,17 @@
 
 #import <XCTest/XCTest.h>
 
-// Implements tests as described here:
-// https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md
-
+/**
+ * Implements tests as described here:
+ * https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md
+ *
+ * This is an abstract class that needs to be subclassed. See |+host|.
+ */
 @interface InteropTests : XCTestCase
-// Returns nil, and as a consequence all tests of the superclass are skipped.
-// Override in a subclass to perform these tests against a specific address.
+/**
+ * Host to send the RPCs to. The base implementation returns nil, which would make all tests to
+ * fail.
+ * Override in a subclass to perform these tests against a specific address.
+ */
 + (NSString *)host;
 @end
diff --git a/src/objective-c/tests/InteropTestsLocalCleartext.m b/src/objective-c/tests/InteropTestsLocalCleartext.m
index 2d7d3c4b2c..56927a8af6 100644
--- a/src/objective-c/tests/InteropTestsLocalCleartext.m
+++ b/src/objective-c/tests/InteropTestsLocalCleartext.m
@@ -31,15 +31,13 @@
  *
  */
 
-// Repeat of the tests in InteropTests.m, but sending the RPCs to a local cleartext server instead
-// of the remote SSL one.
-
 #import <GRPCClient/GRPCCall+Tests.h>
 
 #import "InteropTests.h"
 
 static NSString * const kLocalCleartextHost = @"localhost:5050";
 
+/** Tests in InteropTests.m, sending the RPCs to a local cleartext server. */
 @interface InteropTestsLocalCleartext : InteropTests
 @end
 
diff --git a/src/objective-c/tests/InteropTestsLocalSSL.m b/src/objective-c/tests/InteropTestsLocalSSL.m
index f69f806dcf..9d7afefbfe 100644
--- a/src/objective-c/tests/InteropTestsLocalSSL.m
+++ b/src/objective-c/tests/InteropTestsLocalSSL.m
@@ -31,15 +31,13 @@
  *
  */
 
-// Repeat of the tests in InteropTests.m, but sending the RPCs to a local SSL server instead of the
-// remote one.
-
 #import <GRPCClient/GRPCCall+Tests.h>
 
 #import "InteropTests.h"
 
 static NSString * const kLocalSSLHost = @"localhost:5051";
 
+/** Tests in InteropTests.m, sending the RPCs to a local SSL server. */
 @interface InteropTestsLocalSSL : InteropTests
 @end
 
diff --git a/src/objective-c/tests/InteropTestsRemote.m b/src/objective-c/tests/InteropTestsRemote.m
index 50296cf04e..a67be98431 100644
--- a/src/objective-c/tests/InteropTestsRemote.m
+++ b/src/objective-c/tests/InteropTestsRemote.m
@@ -31,15 +31,13 @@
  *
  */
 
-// Repeat of the tests in InteropTests.m, but sending the RPCs to a local SSL server instead of the
-// remote one.
-
 #import <GRPCClient/GRPCCall+Tests.h>
 
 #import "InteropTests.h"
 
 static NSString * const kRemoteSSLHost = @"grpc-test.sandbox.google.com";
 
+/** Tests in InteropTests.m, sending the RPCs to a remote SSL server. */
 @interface InteropTestsRemote : InteropTests
 @end