QAbstractGrpcChannel: rework documentation

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

src/grpc/qabstractgrpcchannel.cpp

@@ -17,81 +17,65 @@ QT_BEGIN_NAMESPACE
 /*!
     \class QAbstractGrpcChannel
     \inmodule QtGrpc
-    \brief The QAbstractGrpcChannel class is an interface that represents common
+    \brief The QAbstractGrpcChannel class provides an interface for
-    \gRPC channel functionality.
+    implementing the transport layer of \gRPC operations.
 
-    Implement this interface to create your own custom channel for \gRPC
+    Implement this interface to create a custom channel for \gRPC
-    transportation. We provide the QGrpcHttp2Channel, which is a fully featured
+    transportation. The QGrpcHttp2Channel class is provided as a fully featured
-    implementation of the QAbstractGrpcChannel for HTTP/2 communication.
+    implementation of QAbstractGrpcChannel for HTTP/2 communication.
+
+    \sa QGrpcChannelOptions, QGrpcHttp2Channel
 */
 
 /*!
     \fn virtual std::shared_ptr<QAbstractProtobufSerializer> QAbstractGrpcChannel::serializer() const = 0
 
-    This pure virtual function shall return a shared pointer
+    This pure virtual function retrieves the QAbstractProtobufSerializer used
-    to QAbstractProtobufSerializer.
+    for the serialization and deserialization of messages.
-
-    This function is called to obtain the QAbstractProtobufSerializer used
-    to perform serialization and deserialization of the message.
 */
 
 /*!
     \fn virtual void QAbstractGrpcChannel::call(std::shared_ptr<QGrpcOperationContext> operationContext) = 0
     \since 6.7
 
-    This pure virtual function is called by public QAbstractGrpcChannel::call
+//! [abstract-rpc-desc]
-    method when making unary \gRPC call. The \a operationContext is the
+    This pure virtual function is called when a user starts a new RPC through
-    pointer to a channel side \l QGrpcOperationContext primitive that is
+    the generated client interface. The \a operationContext should be used to
-    connected with \l QGrpcCallReply primitive, that is used in
+    communicate with the corresponding RPC handler, which is a derived type of
-    \l QGrpcClientBase implementations.
+    the QGrpcOperation object.
 
-    The function should implement the channel-side logic of unary call. The
+    This function should start the corresponding RPC on the channel side. The
-    implementation must be asynchronous and must not block the thread where
+    implementation must be asynchronous and must not block the calling thread.
-    the function was called.
+
+    \note It is the channel's responsibility to support and restrict the subset
+    of features that its RPC type allows.
+//! [abstract-rpc-desc]
 */
 
 /*!
     \fn virtual void QAbstractGrpcChannel::serverStream(std::shared_ptr<QGrpcOperationContext> operationContext) = 0
     \since 6.7
 
-    This pure virtual function that the starts of the server-side stream. The
+    \include qabstractgrpcchannel.cpp abstract-rpc-desc
-    \a operationContext is the pointer to a channel side
-    \l QGrpcOperationContext primitive that is connected with \l QGrpcServerStream
-    primitive, that is used in \l QGrpcClientBase implementations.
-
-    The function should implement the channel-side logic of server-side stream.
-    The implementation must be asynchronous and must not block the thread where
-    the function was called.
 */
 
 /*!
     \fn virtual void QAbstractGrpcChannel::clientStream(std::shared_ptr<QGrpcOperationContext> operationContext) = 0
     \since 6.7
 
-    This pure virtual function that the starts of the client-side stream. The
+    \include qabstractgrpcchannel.cpp abstract-rpc-desc
-    \a operationContext is the pointer to a channel side
-    \l QGrpcOperationContext primitive that is connected with
-    \l QGrpcClientStream primitive, that is used in \l QGrpcClientBase.
-
-    The function should implement the channel-side logic of client-side stream.
-    The implementation must be asynchronous and must not block the thread where
-    the function was called.
 */
 
 /*!
     \fn virtual void QAbstractGrpcChannel::bidiStream(std::shared_ptr<QGrpcOperationContext> operationContext) = 0
     \since 6.7
 
-    This pure virtual function that the starts of the bidirectional stream. The
+    \include qabstractgrpcchannel.cpp abstract-rpc-desc
-    \a operationContext is the pointer to a channel side
-    \l QGrpcOperationContext primitive that is connected with
-    \l QGrpcBidiStream primitive, that is used in \l QGrpcClientBase.
-
-    The function should implement the channel-side logic of bidirectional
-    stream. The implementation must be asynchronous and must not block the
-    thread where the function was called.
 */
 
+/*!
+    Default-constructs the QAbstractGrpcChannel.
+*/
 QAbstractGrpcChannel::QAbstractGrpcChannel()
     : d_ptr(std::make_unique<QAbstractGrpcChannelPrivate>(QGrpcChannelOptions{}))
 {
@@ -99,21 +83,32 @@ QAbstractGrpcChannel::QAbstractGrpcChannel()
 
 /*!
     \since 6.8
-    Constructs QAbstractGrpcChannel using the private message implementation
+    \internal
-    from the derived class.
+
+    Constructs the QAbstractGrpcChannel using the Private implementation to
+    reuse the d_ptr.
 */
 QAbstractGrpcChannel::QAbstractGrpcChannel(QAbstractGrpcChannelPrivate &dd) : d_ptr(&dd)
 {
 }
 
+/*!
+    Constructs the QAbstractGrpcChannel using the specified \a options.
+*/
 QAbstractGrpcChannel::QAbstractGrpcChannel(const QGrpcChannelOptions &options)
     : d_ptr(std::make_unique<QAbstractGrpcChannelPrivate>(options))
 {
 }
+
+/*!
+    Destroys the QAbstractGrpcChannel.
+*/
 QAbstractGrpcChannel::~QAbstractGrpcChannel() = default;
 
 /*!
-    Returns QGrpcChannelOptions used by the channel.
+    Returns the options utilized by the channel.
+
+    \sa setChannelOptions
 */
 const QGrpcChannelOptions &QAbstractGrpcChannel::channelOptions() const & noexcept
 {
@@ -147,12 +142,13 @@ void QAbstractGrpcChannel::setChannelOptions(QGrpcChannelOptions &&options)
 
 /*!
     \internal
-    Function constructs \l QGrpcCallReply and \l QGrpcOperationContext
-    primitives and makes the required for unary \gRPC call connections
-    between them.
 
-    The function should not be called directly, but only by
+//! [private-rpc-desc]
-    \l QGrpcClientBase implementations.
+    This function is called when a user initiates a new RPC through the
+    generated client interface via QGrpcClientBase. It creates the
+    QGrpcOperationContext and the corresponding RPC handler, establishing the
+    required connections between the two.
+//! [private-rpc-desc]
 */
 std::unique_ptr<QGrpcCallReply> QAbstractGrpcChannel::call(QLatin1StringView method,
                                                            QLatin1StringView service,
@@ -179,12 +175,7 @@ std::unique_ptr<QGrpcCallReply> QAbstractGrpcChannel::call(QLatin1StringView met
 
 /*!
     \internal
-    Function constructs \l QGrpcServerStream and \l QGrpcOperationContext
+    \include qabstractgrpcchannel.cpp private-rpc-desc
-    primitives and makes the required for server-side \gRPC stream connections
-    between them.
-
-    The function should not be called directly, but only by
-    \l QGrpcClientBase implementations.
 */
 std::unique_ptr<QGrpcServerStream>
 QAbstractGrpcChannel::serverStream(QLatin1StringView method, QLatin1StringView service,
@@ -210,12 +201,7 @@ QAbstractGrpcChannel::serverStream(QLatin1StringView method, QLatin1StringView s
 
 /*!
     \internal
-    Function constructs \l QGrpcClientStream and \l QGrpcOperationContext
+    \include qabstractgrpcchannel.cpp private-rpc-desc
-    primitives and makes the required for client-side \gRPC stream connections
-    between them.
-
-    The function should not be called directly, but only by
-    \l QGrpcClientBase.
 */
 std::unique_ptr<QGrpcClientStream>
 QAbstractGrpcChannel::clientStream(QLatin1StringView method, QLatin1StringView service,
@@ -233,12 +219,7 @@ QAbstractGrpcChannel::clientStream(QLatin1StringView method, QLatin1StringView s
 
 /*!
     \internal
-    Function constructs \l QGrpcBidiStream and \l QGrpcOperationContext
+    \include qabstractgrpcchannel.cpp private-rpc-desc
-    primitives and makes the required for bidirectional \gRPC stream connections
-    between them.
-
-    The function should not be called directly, but only by
-    \l QGrpcClientBase.
 */
 std::unique_ptr<QGrpcBidiStream> QAbstractGrpcChannel::bidiStream(QLatin1StringView method,
                                                                   QLatin1StringView service,