Merge pull request #20882 from muxi/port

Port #20767: Add Objective-C Doxygen Documentation

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

@@ -15,11 +15,14 @@
  * limitations under the License.
  *
  */
+
 #import "GRPCCallLegacy.h"
 
 #include <AvailabilityMacros.h>
 
-// Deprecated interface. Please use GRPCCallOptions instead.
+/**
+ * The interface is deprecated. Please use GRPCCallOptions instead for corresponding configurations.
+ */
 @interface GRPCCall (ChannelArg)
 
 + (void)setUserAgentPrefix:(nonnull NSString *)userAgentPrefix forHost:(nonnull NSString *)host;

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

@@ -18,7 +18,9 @@
 
 #import "GRPCCallLegacy.h"
 
-// Deprecated interface. Please use GRPCCallOptions instead.
+/**
+ * The interface is deprecated. Please use GRPCCallOptions instead for corresponding configurations.
+ */
 @interface GRPCCall (ChannelCredentials)
 
 + (BOOL)setTLSPEMRootCerts:(nullable NSString *)pemRootCert

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

@@ -24,7 +24,9 @@ typedef struct stream_engine stream_engine;
 // Transport id for Cronet transport
 extern const GRPCTransportID gGRPCCoreCronetID;
 
-// Deprecated class. Please use the gGRPCCoreCronetID with GRPCCallOptions.transport instead.
+/**
+ * The interface is deprecated. Please use GRPCCallOptions instead for corresponding configurations.
+ */
 @interface GRPCCall (Cronet)
 
 + (void)useCronetWithEngine:(stream_engine*)engine;

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

@@ -22,16 +22,24 @@
 
 @protocol GRPCInterceptorFactory;
 
+/**
+ * The interface for gRPC global interceptor.
+ *
+ * \sa GRPCInterceptor
+ */
 @interface GRPCCall2 (Interceptor)
 
 /**
  * Register a global interceptor's factory in the current process. Only one interceptor can be
  * registered in a process. If another one attempts to be registered, an exception will be raised.
+ *
+ * \param[in] interceptorFactory The factory object that generates the global interceptor for each
+ * call.
  */
 + (void)registerGlobalInterceptor:(nonnull id<GRPCInterceptorFactory>)interceptorFactory;
 
 /**
- * Get the global interceptor's factory.
+ * Get the global interceptor's factory object.
  */
 + (nullable id<GRPCInterceptorFactory>)globalInterceptorFactory;
 

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

@@ -20,7 +20,10 @@
 
 @protocol GRPCAuthorizationProtocol;
 
-// Deprecated interface. Please use GRPCCallOptions instead.
+/**
+ * The interface is deprecated. Please use GRPCCallOptions instead for
+ * corresponding configurations.
+ */
 @interface GRPCCall (OAuth2)
 
 @property(atomic, copy) NSString* oauth2AccessToken;

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

@@ -18,7 +18,9 @@
 
 #import "GRPCCallLegacy.h"
 
-// Deprecated interface. Please use GRPCCallOptions instead.
+/**
+ * The interface is deprecated. Please use GRPCCallOptions instead for corresponding configurations.
+ */
 @interface GRPCCall (Tests)
 
 + (void)useTestCertsPath:(NSString *)certsPath

src/objective-c/GRPCClient/GRPCCall.h

@@ -17,6 +17,8 @@
  */
 
 /**
+ * \mainpage notitle
+ *
  * 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
@@ -55,26 +57,30 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)didReceiveInitialMetadata:(nullable NSDictionary *)initialMetadata;
 
 /**
- * This method is deprecated and does not work with interceptors. To use GRPCCall2 interface with
- * interceptor, implement didReceiveData: instead. To implement an interceptor, please leave this
- * method unimplemented and implement didReceiveData: method instead. If this method and
- * didReceiveRawMessage are implemented at the same time, implementation of this method will be
- * ignored.
- *
  * Issued when a message is received from the server. The message is the raw data received from the
  * server, with decompression and without proto deserialization.
+ *
+ * <b> This method is deprecated and does not work with interceptors.</b> To use GRPCCall2 interface
+ * with interceptor, please implement GRPCResponseHandler::didReceiveData method and leave this
+ * method unimplemented. If this method and didReceiveRawMessage are implemented at the same time,
+ * implementation of this method will be ignored.
  */
 - (void)didReceiveRawMessage:(nullable NSData *)message;
 
 /**
- * Issued when a decompressed message is received from the server. The message is decompressed, and
+ * Issued when gRPC message is received from the server. The data is always decompressed with gRPC
- * deserialized if a marshaller is provided to the call (marshaller is work in progress).
+ * or HTTP compression algorithm specified in the response header. \p data could be any type as
+ * transport layer and interceptors may modify the type of the data (e.g. a Protobuf interceptor may
+ * consume NSData typed data and issue GPBMessage typed data to user). Users should interpret \p
+ * data according to the configuration of their calls. Interceptor authors should not assume the
+ * type of \p data unless an agreement is made on how it should be used in a particular call
+ * setting.
  */
 - (void)didReceiveData:(id)data;
 
 /**
- * Issued when a call finished. If the call finished successfully, \a error is nil and \a
+ * Issued when a call finished. If the call finished successfully, \p error is nil and \p
- * trainingMetadata consists any trailing metadata received from the server. Otherwise, \a error
+ * trailingMetadata consists any trailing metadata received from the server. Otherwise, \p error
  * is non-nil and contains the corresponding error information, including gRPC error codes and
  * error descriptions.
  */
@@ -82,16 +88,16 @@ NS_ASSUME_NONNULL_BEGIN
                                error:(nullable NSError *)error;
 
 /**
- * Issued when flow control is enabled for the call and a message written with writeData: method of
+ * Issued when flow control is enabled for the call and a message written with GRPCCall2::writeData
- * GRPCCall2 is passed to gRPC core with SEND_MESSAGE operation.
+ * is passed to gRPC core with SEND_MESSAGE operation.
  */
 - (void)didWriteData;
 
 @end
 
 /**
- * Call related parameters. These parameters are automatically specified by Protobuf. If directly
+ * HTTP request parameters. If Protobuf is used, these parameters are automatically generated by
- * using the \a GRPCCall2 class, users should specify these parameters manually.
+ * Protobuf. If directly using the GRPCCall2 class, users should specify these parameters manually.
  */
 @interface GRPCRequestOptions : NSObject<NSCopying>
 
@@ -119,7 +125,7 @@ NS_ASSUME_NONNULL_BEGIN
 #pragma mark GRPCCall
 
 /**
- * A \a GRPCCall2 object represents an RPC call.
+ * A GRPCCall2 object represents an RPC call.
  */
 @interface GRPCCall2 : NSObject
 
@@ -169,7 +175,7 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)finish;
 
 /**
- * Tell gRPC to receive the next N gRPC message from gRPC core.
+ * Tell gRPC to receive the next N gRPC messages.
  *
  * This method should only be used when flow control is enabled. When flow control is not enabled,
  * this method is a no-op.

src/objective-c/GRPCClient/GRPCCallLegacy.h

@@ -16,11 +16,6 @@
  *
  */
 
-/**
- * This is the legacy interface of this gRPC library. This API is deprecated and users should use
- * the API in GRPCCall.h. This API exists solely for the purpose of backwards compatibility.
- */
-
 #import <RxLibrary/GRXWriter.h>
 #import "GRPCTypes.h"
 
@@ -28,8 +23,8 @@
 #pragma clang diagnostic ignored "-Wnullability-completeness"
 
 /**
- * This interface is deprecated. Please use \a GRPCCall2.
+ * This is the legacy interface of this gRPC library. This API is deprecated and users should use
- *
+ * GRPCCall2 in GRPCCall.h. This API exists solely for the purpose of backwards compatibility.
  * Represents a single gRPC remote call.
  */
 @interface GRPCCall : GRXWriter

src/objective-c/GRPCClient/GRPCCallOptions.h

@@ -24,6 +24,9 @@ NS_ASSUME_NONNULL_BEGIN
 
 @protocol GRPCInterceptorFactory;
 
+/**
+ * Immutable user configurable options for a gRPC call.
+ */
 @interface GRPCCallOptions : NSObject<NSCopying, NSMutableCopying>
 
 // Call parameters
@@ -194,6 +197,9 @@ NS_ASSUME_NONNULL_BEGIN
 
 @end
 
+/**
+ * Mutable user configurable options for a gRPC call.
+ */
 @interface GRPCMutableCallOptions : GRPCCallOptions<NSCopying, NSMutableCopying>
 
 // Call parameters

src/objective-c/GRPCClient/GRPCInterceptor.h

@@ -17,6 +17,7 @@
  */
 
 /**
+ * \file GRPCInterceptor.h
  * API for interceptors implementation. This feature is currently EXPERIMENTAL and is subject to
  * breaking changes without prior notice.
  *
@@ -24,30 +25,31 @@
  * interceptor on the chain has chances to react to events of the call and make necessary
  * modifications to the call's parameters, data, metadata, or flow.
  *
- *
+ * \verbatim
- *                                   -----------
+                                     -----------
- *                                  | GRPCCall2 |
+                                    | GRPCCall2 |
- *                                   -----------
+                                     -----------
- *                                        |
+                                          |
- *                                        |
+                                          |
- *                           --------------------------
+                             --------------------------
- *                          | GRPCInterceptorManager 1 |
+                            | GRPCInterceptorManager 1 |
- *                           --------------------------
+                             --------------------------
- *                          | GRPCInterceptor 1        |
+                            | GRPCInterceptor 1        |
- *                           --------------------------
+                             --------------------------
- *                                        |
+                                          |
- *                                       ...
+                                         ...
- *                                        |
+                                          |
- *                           --------------------------
+                             --------------------------
- *                          | GRPCInterceptorManager N |
+                            | GRPCInterceptorManager N |
- *                           --------------------------
+                             --------------------------
- *                          | GRPCInterceptor N        |
+                            | GRPCInterceptor N        |
- *                           --------------------------
+                             --------------------------
- *                                        |
+                                          |
- *                                        |
+                                          |
- *                               ------------------
+                                 ------------------
- *                              | GRPCCallInternal |
+                                | GRPCCallInternal |
- *                               ------------------
+                                 ------------------
+   \endverbatim
  *
  * The chain of interceptors is initialized when the corresponding GRPCCall2 object or proto call
  * object (GRPCUnaryProtoCall and GRPCStreamingProtoCall) is initialized. The initialization of the
@@ -70,28 +72,30 @@
  * transitions. Any event not appearing on the diagram means the event is not permitted for that
  * particular state.
  *
- *                                      writeData
+ * \verbatim
- *                                  receiveNextMessages
+                                        writeData
- *                               didReceiveInitialMetadata
+                                    receiveNextMessages
- *                                    didReceiveData
+                                 didReceiveInitialMetadata
- *                                     didWriteData                   receiveNextmessages
+                                      didReceiveData
- *           writeData  -----             -----                 ----  didReceiveInitialMetadata
+                                       didWriteData                   receiveNextmessages
- * receiveNextMessages |     |           |     |               |    | didReceiveData
+             writeData  -----             -----                 ----  didReceiveInitialMetadata
- *                     |     V           |     V               |    V didWriteData
+   receiveNextMessages |     |           |     |               |    | didReceiveData
- *               -------------  start   ---------   finish    ------------
+                       |     V           |     V               |    V didWriteData
- *              | initialized | -----> | started | --------> | half-close |
+                 -------------  start   ---------   finish    ------------
- *               -------------          ---------             ------------
+                | initialized | -----> | started | --------> | half-close |
- *                     |                     |                      |
+                 -------------          ---------             ------------
- *                     |                     | didClose             | didClose
+                       |                     |                      |
- *                     |cancel               | cancel               | cancel
+                       |                     | didClose             | didClose
- *                     |                     V                      |
+                       |cancel               | cancel               | cancel
- *                     |                 ----------                 |
+                       |                     V                      |
- *                      --------------> | finished | <--------------
+                       |                 ----------                 |
- *                                       ----------
+                        --------------> | finished | <--------------
- *                                        |      ^ writeData
+                                         ----------
- *                                        |      | finish
+                                          |      ^ writeData
- *                                         ------  cancel
+                                          |      | finish
- *                                                 receiveNextMessages
+                                           ------  cancel
+                                                   receiveNextMessages
+   \endverbatim
  *
  * Events of requests and responses are dispatched to interceptor objects using the interceptor's
  * dispatch queue. The dispatch queue should be serial queue to make sure the events are processed
@@ -117,7 +121,7 @@ NS_ASSUME_NONNULL_BEGIN
 @protocol GRPCResponseHandler;
 
 /**
- * The GRPCInterceptorInterface defines the request events that can occur to an interceptr.
+ * The GRPCInterceptorInterface defines the request events that can occur to an interceptor.
  */
 @protocol GRPCInterceptorInterface<NSObject, GRPCDispatchable>
 
@@ -150,8 +154,8 @@ NS_ASSUME_NONNULL_BEGIN
 @end
 
 /**
- * An interceptor factory object should be used to create interceptor object for the call at the
+ * An interceptor factory object is used to create interceptor object for the call at the call
- * call start time.
+ * start time.
  */
 @protocol GRPCInterceptorFactory
 

src/objective-c/GRPCClient/GRPCTransport.h

@@ -26,7 +26,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  * The default transport implementations available in gRPC. These implementations will be provided
- * by gRPC by default unless explicitly excluded.
+ * by gRPC by default unless explicitly excluded by the build system.
  */
 extern const struct GRPCDefaultTransportImplList {
   const GRPCTransportID core_secure;
@@ -51,7 +51,7 @@ NSUInteger TransportIDHash(GRPCTransportID);
 /** The factory to create a transport. */
 @protocol GRPCTransportFactory<NSObject>
 
-/** Create a transport implementation. */
+/** Create a transport implementation instance. */
 - (GRPCTransport *)createTransportWithManager:(GRPCTransportManager *)transportManager;
 
 /** Get a list of factories for transport inteceptors. */
@@ -67,7 +67,7 @@ NSUInteger TransportIDHash(GRPCTransportID);
 /**
  * Register a transport implementation with the registry. All transport implementations to be used
  * in a process must register with the registry on process start-up in its +load: class method.
- * Parameter \a transportID is the identifier of the implementation, and \a factory is the factory
+ * Parameter \p transportID is the identifier of the implementation, and \p factory is the factory
  * object to create the corresponding transport instance.
  */
 - (void)registerTransportWithID:(GRPCTransportID)transportID

src/objective-c/GRPCClient/GRPCTypes.h

@@ -138,7 +138,12 @@ typedef NS_ENUM(NSUInteger, GRPCCallSafety) {
   GRPCCallSafetyCacheableRequest = 2,
 };
 
-// Compression algorithm to be used by a gRPC call
+/**
+ * Compression algorithm to be used by a gRPC call.
+ *
+ * <b>This enumeration and corresponding call option GRPCCallOptions.transportType are deprecated by
+ * the call option GRPCCallOptions.transport. </b>
+ */
 typedef NS_ENUM(NSUInteger, GRPCCompressionAlgorithm) {
   GRPCCompressNone = 0,
   GRPCCompressDeflate,
@@ -146,7 +151,7 @@ typedef NS_ENUM(NSUInteger, GRPCCompressionAlgorithm) {
   GRPCStreamCompressGzip,
 };
 
-// GRPCCompressAlgorithm is deprecated; use GRPCCompressionAlgorithm
+/** GRPCCompressAlgorithm is deprecated. */
 typedef GRPCCompressionAlgorithm GRPCCompressAlgorithm;
 
 /** The transport to be used by a gRPC call */

src/objective-c/ProtoRPC/ProtoRPC.h

@@ -53,8 +53,8 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)didReceiveProtoMessage:(nullable GPBMessage *)message;
 
 /**
- * Issued when a call finished. If the call finished successfully, \a error is nil and \a
+ * Issued when a call finished. If the call finished successfully, \p error is nil and \p
- * trainingMetadata consists any trailing metadata received from the server. Otherwise, \a error
+ * trainingMetadata consists any trailing metadata received from the server. Otherwise, \p error
  * is non-nil and contains the corresponding error information, including gRPC error codes and
  * error descriptions.
  */

templates/tools/doxygen/Doxyfile.objc.internal.template

@@ -0,0 +1,4 @@
+%YAML 1.2
+--- |
+  <%namespace file="Doxyfile.objc.include" import="gen_doxyfile"/>\
+  ${gen_doxyfile(True)}

templates/tools/doxygen/Doxyfile.objc.template

@@ -0,0 +1,4 @@
+%YAML 1.2
+--- |
+  <%namespace file="Doxyfile.objc.include" import="gen_doxyfile"/>\
+  ${gen_doxyfile(False)}

tools/doxygen/run_doxygen.sh

@@ -19,7 +19,7 @@ set -ex
 # change to grpc repo root
 cd $(dirname $0)/../..
 
-for i in core c++ core.internal c++.internal
+for i in core c++ core.internal c++.internal objc objc.internal
 do
 	rm -rf doc/ref/$i
 	mkdir -p doc/ref/$i