Update links to the QtGrpc documentation

Add QtGrpc index and classes documentation pages.
Fix missing links to QtGrpc documentation.
The modules are now consistently named 'Qt GRPC', 'Qt Protobuf'.

Pick-to: 6.5
Change-Id: Iabd91336c871e43c97c49712a52f3aa82f7e75a5
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>

CMakeLists.txt

@@ -6,7 +6,7 @@ cmake_minimum_required(VERSION 3.16)
 include(.cmake.conf)
 project(QtGrpc
     VERSION "${QT_REPO_MODULE_VERSION}"
-    DESCRIPTION "Qt gRPC and Protobuf generator and bindings."
+    DESCRIPTION "Qt GRPC and Protobuf generator and bindings."
     HOMEPAGE_URL "https://qt.io"
     LANGUAGES CXX C
 )

src/grpc/configure.cmake

@@ -17,7 +17,7 @@ qt_feature("native_grpc" PUBLIC
     CONDITION TARGET WrapgRPC::WrapLibgRPC
 )
 
-qt_configure_add_summary_section(NAME "QtGrpc")
+qt_configure_add_summary_section(NAME "Qt GRPC")
 qt_configure_add_summary_entry(ARGS "grpc")
 qt_configure_add_summary_entry(ARGS "native_grpc")
 qt_configure_end_summary_section()

src/grpc/doc/index.qdoc

@@ -1,24 +0,0 @@
-// Copyright (C) 2022 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-/*!
-    \page qtgrpc-index.html
-    \title Qt gRPC
-    \brief Provides a gRPC.
-
-    \section1 Licenses
-
-    QtGrpc is available under commercial licenses from \l{The Qt Company}.
-    In addition, it is available under the \l {GNU General Public License, version 3}.
-    See \l{Qt Licensing} for further details.
-
-    \section1 Reference Documentation
-    \list
-    \li \l{Qt gRPC Overview}{Overview}
-    \li \l{Qt gRPC C++ Classes}{C++ Classes}
-    \endlist
-
-    \section1 Trademarks
-
-    gRPC\reg is a registered trademark of The Linux Foundation.
-    Please see \l https://grpc.io/ for more information.
-*/

src/grpc/doc/overview.qdoc

@@ -1,16 +0,0 @@
-// Copyright (C) 2022 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-
-/*!
-\page qtgrpc-overview.html
-\title Qt gRPC Overview
-\brief Provides insight into the QtGrpc module.
-
-QtGrpc provides support for comunicating with gRPC services.
-
-QtGrpc together with QtProtobuf allows users to define data and messages in \c proto files,
-and then use the code generators, which generates code allowing accessors for fields
-and gRPC (Google Remote Procedure Calls) services in the Qt framework.
-Such code allows users to send calls or stream messages to the server.
-
-*/

src/grpc/doc/qtgrpc-index.qdoc

@@ -0,0 +1,33 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+/*!
+    \page qtgrpc-index.html
+    \title Qt GRPC
+    \brief Provides support for communicating with gRPC services.
+
+    Qt GRPC together with \l{Qt Protobuf} allow you to define data and messages
+    in \c proto files, and then use the code generators,
+    which generate code allowing accessors for fields
+    and gRPC services in the Qt framework.
+    Such code allows users to communicate with the server by sending calls
+    or stream messages.
+
+    \section1 Licenses and Trademarks
+
+    Qt GRPC is available under commercial licenses from \l{The Qt Company}.
+    In addition, it is available under the \l {GNU General Public License, version 3}.
+    See \l{Qt Licensing} for further details.
+
+    gRPC\reg is a registered trademark of The Linux Foundation.
+    Please see \l https://grpc.io/ for more information.
+
+    \section1 Reference Documentation
+    \list
+    \li \l{Qt GRPC C++ Classes}{C++ Classes}
+    \endlist
+
+    \section1 CMake API
+    \list
+        \li \l{CMake Commands in Qt6 GRPC}
+    \endlist
+*/

src/grpc/doc/qtgrpc.qdocconf

@@ -1,7 +1,7 @@
 include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
 
-project                 = QtGrpc
+project                 = QtGRPC
-description             = Qt gRPC Reference Documentation
+description             = Qt GRPC Reference Documentation
 version                 = $QT_VERSION
 
 examplesinstallpath     = grpc
@@ -11,19 +11,19 @@ qhp.projects            = QtGrpc
 qhp.QtGrpc.file                = qtgrpc.qhp
 qhp.QtGrpc.namespace           = org.qt-project.qtgrpc.$QT_VERSION_TAG
 qhp.QtGrpc.virtualFolder       = qtgrpc
-qhp.QtGrpc.indexTitle          = Qt Grpc
+qhp.QtGrpc.indexTitle          = Qt GRPC
 qhp.QtGrpc.indexRoot           =
 
 qhp.QtGrpc.subprojects = qmltypes examples classes
 qhp.QtGrpc.subprojects.qmltypes.title = QML Types
-qhp.QtGrpc.subprojects.qmltypes.indexTitle = Qt gRPC QML Types
+qhp.QtGrpc.subprojects.qmltypes.indexTitle = Qt GRPC QML Types
 qhp.QtGrpc.subprojects.qmltypes.selectors = qmlclass
 qhp.QtGrpc.subprojects.qmltypes.sortPages = true
 qhp.QtGrpc.subprojects.examples.title = Examples
-qhp.QtGrpc.subprojects.examples.indexTitle = Qt gRPC Examples and Tutorials
+qhp.QtGrpc.subprojects.examples.indexTitle = Qt GRPC Examples
 qhp.QtGrpc.subprojects.examples.selectors = doc:example
 qhp.QtGrpc.subprojects.classes.title      = C++ Classes
-qhp.QtGrpc.subprojects.classes.indexTitle = Qt gRPC C++ Classes
+qhp.QtGrpc.subprojects.classes.indexTitle = Qt GRPC C++ Classes
 qhp.QtGrpc.subprojects.classes.selectors  = class doc:headerfile
 qhp.QtGrpc.subprojects.classes.sortPages  = true
 
@@ -35,9 +35,9 @@ exampledirs +=  ../../../examples/grpc
 
 imagedirs   += images
 
-navigation.landingpage = "Qt gRPC"
+navigation.landingpage = "Qt GRPC Overview"
-navigation.cppclassespage = "Qt gRPC C++ Classes"
+navigation.cppclassespage = "Qt GRPC C++ Classes"
-#navigation.qmltypespage = "Qt gRPC QML Types"
+navigation.qmltypespage = "Qt GRPC QML Types"
 
 tagfile                 = qtgrpc.tags
 

src/grpc/doc/src/cmake-commands.qdoc

@@ -0,0 +1,53 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\group cmake-commands-qtgrpc
+\title CMake Commands in Qt6 GRPC
+
+The following CMake commands are defined when Qt6::Protobuf is loaded, for
+instance with:
+
+\code
+find_package(Qt6 REQUIRED COMPONENTS Protobuf)
+\endcode
+
+Additionally, to find the Qt GRPC module, use CMake command:
+\code
+find_package(Qt6 REQUIRED COMPONENTS Grpc)
+\endcode
+
+To generate gRPC services using Qt GRPC and link them with your program consider
+the following example:
+
+\code
+cmake_minimum_required(VERSION 3.16...3.22)
+project(MyProject)
+
+find_package(Qt6 REQUIRED COMPONENTS Grpc Protobuf)
+qt_standard_project_setup()
+
+qt_add_grpc(MyGrpcClient CLIENT
+    PROTO_FILES
+        path/to/service.proto
+        path/to/message.proto
+        path/to/other_message.proto
+    PROTO_INCLUDES
+        /path/to/proto/include
+)
+target_link_libraries(MyGrpcClient PRIVATE Qt6::Grpc)
+
+qt_add_executable(MyApp main.cpp)
+
+target_link_libraries(MyApp PRIVATE MyGrpcClient)
+\endcode
+
+In the example above, you call the \c{qt_add_protobuf()}
+CMake function to generate a library called \c{MyGrpcClient}.
+Then you link the generated library with \c{Qt6::Grpc} library.
+
+We then create a target for an executable called \c{MyApp} which we link
+to the \c{MyGrpcClient} library.
+
+\sa{CMake Commands in Qt6 Protobuf}
+*/

src/grpc/doc/src/qt-add-grpc-example.qdocinc

@@ -1,29 +0,0 @@
-\badcode
-cmake_minimum_required(VERSION 3.16...3.22)
-project(MyProject)
-
-find_package(Qt6 REQUIRED COMPONENTS Grpc Protobuf)
-qt_standard_project_setup()
-
-qt_add_grpc(MyGrpcClient CLIENT
-    PROTO_FILES
-        path/to/service.proto
-        path/to/message.proto
-        path/to/other_message.proto
-    PROTO_INCLUDES
-        /path/to/proto/include
-)
-target_link_libraries(MyGrpcClient PRIVATE Qt6::Grpc)
-
-qt_add_executable(MyApp main.cpp)
-
-target_link_libraries(MyApp PRIVATE MyGrpcClient)
-\endcode
-
-In the example above we generate a library called \c{MyGrpcClient}
-by calling the \l{qt_add_grpc.html}{qt_add_grpc()} CMake function.
-
-Then we are linking generated library with \c{Qt6::Grpc} library.
-
-We then create a target for an executable called \c{MyApp} which we link
-to the \c{MyGrpcClient} library.

src/grpc/doc/src/qtgrpc-module.qdoc

@@ -1,11 +1,13 @@
 // Copyright (C) 2022 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 /*!
-    \module QtGrpc
+    \module QtGRPC
     \modulestate Technical Preview
-    \title Qt gRPC C++ Classes
+    \title Qt GRPC C++ Classes
+    \ingroup frameworks-technologies
     \qtcmakepackage Grpc
+    \qtvariable grpc
     \since 6.5
 
-    \brief Provides gRPC support for Qt.
+    \brief The Qt GRPC module provides support for communicating with gRPC services.
 */

src/grpc/qabstractgrpcchannel.cpp

@@ -8,7 +8,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QAbstractGrpcChannel
-    \inmodule QtGrpc
+    \inmodule QtGRPC
     \brief The QAbstractGrpcChannel class is interface that represents common
     gRPC channel functionality.
 

src/grpc/qabstractgrpcclient.cpp

@@ -19,7 +19,7 @@ namespace {
 static QString threadSafetyWarning(QLatin1StringView methodName)
 {
     return QLatin1StringView("%1 is called from a different thread.\n"
-                             "QtGrpc doesn't guarantee thread safety on the channel level.\n"
+                             "Qt GRPC doesn't guarantee thread safety on the channel level.\n"
                              "You have to be confident that channel routines are working in "
                              "the same thread as QAbstractGrpcClient.")
             .arg(methodName);
@@ -28,7 +28,7 @@ static QString threadSafetyWarning(QLatin1StringView methodName)
 
 /*!
     \class QAbstractGrpcClient
-    \inmodule QtGrpc
+    \inmodule QtGRPC
     \brief The QAbstractGrpcClient class is bridge between gRPC clients
     and channels.
 
@@ -108,7 +108,7 @@ QAbstractGrpcClient::~QAbstractGrpcClient() = default;
     Parameters and return values will be serialized to the channel
     in a format it supports.
 
-    \note \b Warning: QtGrpc doesn't guarantee thread safety on channel level.
+    \note \b Warning: Qt GRPC doesn't guarantee thread safety on the channel level.
     You have to invoke the channel-related functions on the same thread as
     QAbstractGrpcClient.
 */

src/grpc/qabstractgrpcservice.cpp

@@ -10,7 +10,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QAbstractGrpcService
-    \inmodule QtGrpc
+    \inmodule QtGRPC
     \brief The QAbstractGrpcService class is a bridge between gRPC service.
 
     QAbstractGrpcService provides set of bridge functions for server classes

src/grpc/qgrpccallreply.cpp

@@ -11,7 +11,7 @@ using namespace Qt::StringLiterals;
 
 /*!
     \class QGrpcCallReply
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcCallReply class contains data for asynchronous call
     of gRPC client API.

src/grpc/qgrpcchannel.cpp

@@ -31,7 +31,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QGrpcChannel
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcChannel class is a gRPC-cpp native api implementation of
     QAbstractGrpcChannel interface.

src/grpc/qgrpccredentials.cpp

@@ -8,7 +8,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QGrpcCallCredentials
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcCallCredentials is the base class for gRPC call credentials.
 
@@ -21,7 +21,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QGrpcChannelCredentials
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcChannelCredentials is the base class for gRPC
     channel credentials.
@@ -36,7 +36,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QGrpcCredentials
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcCredentials class is a combination of call
     and channel credentials that is used by gRPC channels to communicate

src/grpc/qgrpchttp2channel.cpp

@@ -24,7 +24,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QGrpcHttp2Channel
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcHttp2Channel class is an HTTP/2 implementation of
     QAbstractGrpcChannel interface.

src/grpc/qgrpcinsecurecredentials.cpp

@@ -6,7 +6,7 @@
 
 /*!
     \class QGrpcInsecureCallCredentials
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcInsecureCallCredentials class is a dummy implementation
     of QGrpcCallCredentials.
@@ -17,7 +17,7 @@
 
 /*!
     \class QGrpcInsecureChannelCredentials
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcInsecureChannelCredentials class is a dummy implementation
     of QGrpcChannelCredentials.

src/grpc/qgrpcoperation.cpp

@@ -10,7 +10,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QGrpcOperation
-    \inmodule QtGrpc
+    \inmodule QtGRPC
     \brief The QGrpcOperation class implements common logic to
            handle communication in Grpc channel.
 */

src/grpc/qgrpcsslcredentials.cpp

@@ -6,7 +6,7 @@
 
 /*!
     \class QGrpcSslCredentials
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcSslCredentials class.
 

src/grpc/qgrpcstatus.cpp

@@ -8,7 +8,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QGrpcStatus
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcStatus class contains information about last gRPC operation.
 

src/grpc/qgrpcstream.cpp

@@ -10,7 +10,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QGrpcStream
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcStream class.
 

src/grpc/qgrpcuserpasswordcredentials.cpp

@@ -13,7 +13,7 @@ constexpr char defaultPasswordFieldName[] = "user-password";
 
 /*!
     \class QGrpcUserPasswordCredentials
-    \inmodule QtGrpc
+    \inmodule QtGRPC
 
     \brief The QGrpcUserPasswordCredentials class is a reference
     implementation of simple user-password call authentication.

src/protobuf/configure.cmake

@@ -11,12 +11,12 @@ qt_find_package(WrapProtoc PROVIDED_TARGETS WrapProtoc::WrapProtoc MODULE_NAME g
 
 qt_feature("qtprotobufgen" PRIVATE
     SECTION "Utilities"
-    LABEL "Qt protobuf generator"
+    LABEL "Qt Protobuf generator"
     PURPOSE "Provides support for generating Qt-based classes for use with Protocol Buffers."
     CONDITION (TARGET WrapProtobuf::WrapLibProtoc AND TARGET WrapProtobuf::WrapLibProtobuf AND
         TARGET WrapProtoc::WrapProtoc) OR (CMAKE_CROSSCOMPILING AND NOT QT_FORCE_BUILD_TOOLS)
 )
 
-qt_configure_add_summary_section(NAME "QtProtobuf tools")
+qt_configure_add_summary_section(NAME "Qt Protobuf tools")
 qt_configure_add_summary_entry(ARGS "qtprotobufgen")
 qt_configure_end_summary_section()

src/protobuf/doc/src/qtprotobuf.qdoc

@@ -27,7 +27,7 @@
     \module QtProtobuf
     \modulestate Technical Preview
     \title Qt Protobuf C++ Classes
-    \qtcmakepackage Protobuf
+    \qtcmakepackage protobuf
     \since 6.5
     \brief Provides protocol buffers support in Qt.
 */

src/tools/qtprotobufgen/CMakeLists.txt

@@ -3,7 +3,7 @@
 
 qt_get_tool_target_name(target_name qtprotobufgen)
 qt_internal_add_tool(${target_name}
-    TARGET_DESCRIPTION "Qt protobuf generator"
+    TARGET_DESCRIPTION "Qt Protobuf generator"
     INSTALL_DIR "${INSTALL_LIBEXECDIR}"
     TOOLS_TARGET Protobuf
     CORE_LIBRARY None

tests/auto/grpc/shared/test_server/CMakeLists.txt

@@ -6,7 +6,7 @@ find_package(WrapProtobuf)
 find_package(WrapgRPC)
 
 if(NOT WrapgRPCPlugin_FOUND OR NOT WrapProtobuf_FOUND OR NOT WrapgRPC_FOUND)
-    message(WARNING "Dependencies of QtGrpc test server not found. Skipping.")
+    message(WARNING "Dependencies of Qt GRPC test server not found. Skipping.")
     return()
 endif()