From 2f970bc3c27a3607f782c4c14fbe1fbe55b29440 Mon Sep 17 00:00:00 2001
From: Dennis Oberst <dennis.oberst@qt.io>
Date: Mon, 3 Mar 2025 21:10:49 +0100
Subject: [PATCH] Docs: Add transportation info for QGrpcHttp2Channel

We should be clearer about what transportation is used and when.
Otherwise, our users are left in the dark.

Task-number: QTBUG-134273
Pick-to: 6.9 6.9.0 6.8 6.8.3
Change-Id: I6d1da9236447521a53b197808c55c89c49fbd4c2
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
---
 src/grpc/qgrpchttp2channel.cpp | 39 ++++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/src/grpc/qgrpchttp2channel.cpp b/src/grpc/qgrpchttp2channel.cpp
index 853c8747..7314d26c 100644
--- a/src/grpc/qgrpchttp2channel.cpp
+++ b/src/grpc/qgrpchttp2channel.cpp
@@ -64,6 +64,39 @@ using namespace QtGrpc;
     {serializationFormat}, or other options by constructing it with a
     QGrpcChannelOptions containing the required customizations.
 
+    \section2 Transportation scheme
+
+    The QGrpcHttp2Channel implementation prefers different transportation
+    methods based on the provided \c{hostUri}, \l{QUrl::}{scheme} and options.
+    The following criteria applies:
+
+    \table
+    \header
+        \li Scheme
+        \li Description
+        \li Default Port
+        \li Requirements
+        \li Example
+    \row
+        \li \c{http}
+        \li Unencrypted HTTP/2 over TCP
+        \li 80
+        \li None
+        \li \c{http://localhost}
+    \row
+        \li \c{https}
+        \li TLS-encrypted HTTP/2 over TCP
+        \li 443
+        \li QSslSocket support \b{AND} (scheme \b{OR} \l{QGrpcChannelOptions::}{sslConfiguration})
+        \li \c{https://localhost}
+    \row
+        \li \c{unix}
+        \li Unix domain socket in filesystem path
+        \li ✗
+        \li QLocalSocket support \b{AND} scheme
+        \li \c{unix:///tmp/grpc.socket}
+    \endtable
+
     \section2 Content-Type
 
     The \e{content-type} in \gRPC over HTTP/2 determines the message
@@ -927,7 +960,8 @@ void QGrpcHttp2ChannelPrivate::deleteHandler(Http2Handler *handler)
 ///
 
 /*!
-    Constructs QGrpcHttp2Channel with \a hostUri.
+    Constructs QGrpcHttp2Channel with \a hostUri. Please see the
+    \l{Transportation scheme} section for more information.
 */
 QGrpcHttp2Channel::QGrpcHttp2Channel(const QUrl &hostUri)
     : d_ptr(std::make_unique<QGrpcHttp2ChannelPrivate>(hostUri, this))
@@ -935,7 +969,8 @@ QGrpcHttp2Channel::QGrpcHttp2Channel(const QUrl &hostUri)
 }
 
 /*!
-    Constructs QGrpcHttp2Channel with \a hostUri and \a options.
+    Constructs QGrpcHttp2Channel with \a hostUri and \a options. Please see the
+    \l{Transportation scheme} section for more information.
 */
 QGrpcHttp2Channel::QGrpcHttp2Channel(const QUrl &hostUri, const QGrpcChannelOptions &options)
     : QAbstractGrpcChannel(options),