QGrpcHttp2Channel: rework documentation

Task-number: QTBUG-125406
Pick-to: 6.9 6.8
Change-Id: Ibad1355d15f54aa0e5eac949fbbe0efa7a2fed8f
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>

src/grpc/qgrpchttp2channel.cpp

@@ -47,57 +47,71 @@ using namespace QtGrpc;
 /*!
     \class QGrpcHttp2Channel
     \inmodule QtGrpc
+    \brief The QGrpcHttp2Channel class provides a HTTP/2 transport layer
+    for \gRPC communication.
 
-    \brief The QGrpcHttp2Channel class is an HTTP/2-based of
+    The QGrpcHttp2Channel class implements QAbstractGrpcChannel, enabling \gRPC
-    QAbstractGrpcChannel, based on \l {Qt Network} HTTP/2 implementation.
+    communication carried over \l{https://datatracker.ietf.org/doc/html/rfc7540}
+    {HTTP/2 framing}.
 
-    Uses \l QGrpcChannelOptions and \l QGrpcCallOptions
+    HTTP/2 introduces several advantages over its predecessor, HTTP/1.1, making
-    to control the HTTP/2 communication with the server.
+    QGrpcHttp2Channel well-suited for high-performance, real-time applications
+    that require efficient communication, without sacrificing security or
+    reliability, by using multiplexed TCP connections.
 
-    Use \l QGrpcChannelOptions to set the SSL configuration,
+    The channel can be customized with \l{Secure Sockets Layer (SSL)
-    application-specific HTTP/2 headers, and connection timeouts.
+    Classes}{SSL} support, a custom \l{QGrpcChannelOptions::}
+    {serializationFormat}, or other options by constructing it with a
+    QGrpcChannelOptions containing the required customizations.
 
-    \l QGrpcCallOptions control channel parameters for the
+    \section2 Content-Type
-    specific unary call or \gRPC stream.
 
-    QGrpcHttp2Channel uses QGrpcChannelOptions to select the serialization
+    The \e{content-type} in \gRPC over HTTP/2 determines the message
-    format for the protobuf messages. The serialization format can be set
+    serialization format. It must start with \c{application/grpc} and can
-    either using the \c {content-type} metadata or by setting the
+    include a suffix. The format follows this scheme:
-    \l QGrpcChannelOptions::serializationFormat directly.
 
-    Using the following example you can create a QGrpcHttp2Channel with the
-    JSON serialization format using the \c {content-type} metadata:
     \code
-        auto channelJson = std::make_shared<
+        "content-type": "application/grpc" [("+proto" / "+json" / {custom})]
-        QGrpcHttp2Channel>(QGrpcChannelOptions{ QUrl("http://localhost:50051", QUrl::StrictMode) }
-                               .withMetadata({ { "content-type"_ba,
-                                                 "application/grpc+json"_ba } }));
     \endcode
 
-    Also you can use own serializer and custom \c {content-type} as following:
+    For example:
+    \list
+        \li \c{application/grpc+proto} specifies Protobuf encoding.
+        \li \c{application/grpc+json} specifies JSON encoding.
+    \endlist
+
+    The serialization format can be configured either by specifying the \c
+    {content-type} inside the metadata or by setting the \l{QGrpcChannelOptions::}
+    {serializationFormat} directly. By default, the \c {application/grpc}
+    content-type is used.
+
+    To configure QGrpcHttp2Channel with the JSON serialization format using
+    \c {content-type} metadata:
+
     \code
-        class DummySerializer : public QAbstractProtobufSerializer
+        auto jsonChannel = std::make_shared<QGrpcHttp2Channel>(
-        {
+            QUrl("http://localhost:50051"_L1),
-            ...
+            QGrpcChannelOptions().setMetadata({
-        };
+                { "content-type"_ba, "application/grpc+json"_ba },
-        auto channel = std::make_shared<
+            })
-            QGrpcHttp2Channel>(QUrl("http://localhost:50051", QUrl::StrictMode), QGrpcChannelOptions{}
+        );
-                               .setSerializationFormat(QGrpcSerializationFormat{ "dummy",
-                                                          std::make_shared<DummySerializer>() }));
     \endcode
 
-    QGrpcHttp2Channel will use the \c DummySerializer to serialize
+    For a custom serializer and \c {content-type}, you can directly set the
-    and deserialize protobuf message and use the
+    serialization format:
-    \c { content-type: application/grpc+dummy } header when sending
-    HTTP/2 requests to server.
 
-    \l QGrpcChannelOptions::serializationFormat has higher priority and
+    \include qgrpcserializationformat.cpp custom-serializer-code
-    if the \c {content-type} metadata suffix doesn't match the
-    \l QGrpcSerializationFormat::suffix of the specified
-    \l QGrpcChannelOptions::serializationFormat QGrpcHttp2Channel produces
-    warning.
 
-    \sa QGrpcChannelOptions, QGrpcCallOptions, QSslConfiguration
+    \code
+        auto dummyChannel = std::make_shared<QGrpcHttp2Channel>(
+            QUrl("http://localhost:50051"_L1),
+            QGrpcChannelOptions().setSerializationFormat(dummyFormat)
+        );
+    \endcode
+
+    \include qgrpcserializationformat.cpp custom-serializer-desc
+
+    \sa QAbstractGrpcChannel, QGrpcChannelOptions, QGrpcSerializationFormat
 */
 
 namespace {
@@ -870,7 +884,7 @@ QUrl QGrpcHttp2Channel::hostUri() const
 
 /*!
     \internal
-    Implementation of unary \gRPC call based on \l QNetworkAccessManager.
+    Initiates a unary \gRPC call.
 */
 void QGrpcHttp2Channel::call(std::shared_ptr<QGrpcOperationContext> operationContext)
 {
@@ -879,7 +893,7 @@ void QGrpcHttp2Channel::call(std::shared_ptr<QGrpcOperationContext> operationCon
 
 /*!
     \internal
-    Implementation of server-side \gRPC stream based on \l QNetworkAccessManager.
+    Initiates a server-side \gRPC stream.
 */
 void QGrpcHttp2Channel::serverStream(std::shared_ptr<QGrpcOperationContext> operationContext)
 {
@@ -888,7 +902,7 @@ void QGrpcHttp2Channel::serverStream(std::shared_ptr<QGrpcOperationContext> oper
 
 /*!
     \internal
-    Implementation of client-side \gRPC stream based on \l QNetworkAccessManager.
+    Initiates a client-side \gRPC stream.
 */
 void QGrpcHttp2Channel::clientStream(std::shared_ptr<QGrpcOperationContext> operationContext)
 {
@@ -897,7 +911,7 @@ void QGrpcHttp2Channel::clientStream(std::shared_ptr<QGrpcOperationContext> oper
 
 /*!
     \internal
-    Implementation of bidirectional \gRPC stream based on \l QNetworkAccessManager.
+    Initiates a bidirectional \gRPC stream.
 */
 void QGrpcHttp2Channel::bidiStream(std::shared_ptr<QGrpcOperationContext> operationContext)
 {
@@ -905,7 +919,8 @@ void QGrpcHttp2Channel::bidiStream(std::shared_ptr<QGrpcOperationContext> operat
 }
 
 /*!
-    Returns the newly created QProtobufSerializer shared pointer.
+    \internal
+    Returns the serializer of the channel.
 */
 std::shared_ptr<QAbstractProtobufSerializer> QGrpcHttp2Channel::serializer() const
 {