Update well-known types registration

- Add extra documentation for well-known types
- Add extra documentation for generator

Fixes: #80, #91

README.md

@@ -94,7 +94,7 @@ cpack -G DEB ..
 Download and install:
 
 - Qt 5.12.3 or higher [1](https://download.qt.io/official_releases/qt/)
-- cmake-3.1 or higher [2](https://cmake.org/download/)
+- cmake-3.6 or higher [2](https://cmake.org/download/)
 - Strawberry perl 5.28 [3](http://strawberryperl.com/)
 - GoLang 1.10 or higher [4](https://golang.org/dl/)
 - Yasm 1.3 or higher [5](http://yasm.tortall.net/Download.html)
@@ -191,8 +191,6 @@ GENERATED_HEADERS ${GENERATED_HEADERS})
 
 qtprotobuf_generate is cmake helper function that automatically generates STATIC library target from your .proto files
 
-Due to cmake restrictions it's required to specify resulting artifacts manually as list of header files expected after generator job finished.
-
 ***Parameters:***
 
 *TARGET* - name of you target that generated code archive will be linked to
@@ -263,7 +261,7 @@ QT += grpc #for grpc libraries support
 ```
 To generate source code and link it to you project use predefined *qtprotobuf_generate* function
 
-### CMake functions reference
+### qmake functions reference
 #### qtprotobuf_generate([generate_qml=false])
 
 qtprotobuf_generate is qmake helper [test function](https://doc.qt.io/qt-5/qmake-language.html#test-functions) that generates QtProtobuf source code based on files provided by PROTO_FILES global context variable

src/generator/generator.h

@@ -40,6 +40,81 @@ class GeneratorContext;
 
 namespace QtProtobuf {
 namespace generator {
+/*!
+ * \defgroup generator
+ *
+ * \brief QtProtobuf code generator for protobuf messages and grpc services
+ *
+ * \details QtProtobuf code generator is program to be used in conjunction with proto compiler aka protoc.
+ *
+ * It might be used in few ways:
+ *  - manualy
+ *  - \ref cmake "CMake macro"
+ *  - \ref qmake "qmake macro"
+ *
+ * \section Manual usage
+ *
+ * \code
+ * [QT_PROTOBUF_OPTIONS="[SINGLE|MULTI]:QML:COMMENTS"] protoc --plugin=protoc-gen-qtprotobuf=<path/to/bin/>qtprotobufgen --qtprotobuf_out=<output_dir> [-I/extra/proto/include/path] <protofile>.proto
+ * \endcode
+ *
+ * Generator supports options that could be provided as environment variable to tune generation.
+ * Following options are supported:
+ *
+ * *SINGLE* - enables single-file generation when for each *.proto* file single pair of *.h* *.cpp* files is generated
+ *
+ * \note Enabled by default. Excluded by SINGLE
+ *
+ * *MULTI* - enables multi-file generation when for each message separate pair of *.h* *.cpp*
+ *
+ * \note Has higher priority than SINGLE
+ *
+ * *QML* - enables QML code generation in protobuf classes. If is set QML-related code for lists and QML registration to be generated.
+ *
+ * *COMMENTS* - enables comments copying from .proto files
+ *
+ * \section cmake CMake
+ *
+ * For CMake based project QtProtobuf has macroses those should be used to generate code and in link it to your project:
+ *
+ * - \ref cmake_qtprotobuf_generate
+ * - \ref cmake_qtprotobuf_link_archive
+ *
+ *
+ * \subsection cmake_qtprotobuf_generate qtprotobuf_generate
+ *
+ * \brief qtprotobuf_generate is cmake helper function that automatically generates STATIC library target from your .proto files
+ *
+ * \param TARGET name of you target that generated code archive will be linked to
+ * \param GENERATED_TARGET name that will be used for generated archive library target. It's usefull when you supposed to have multiple generated targets to be linked to single one.
+ * \param OUT_DIR output directory that will contain generated artifacts. Usually subfolder in build directory should be used
+ * \param GENERATED_HEADERS List of header files expected after generator job finished
+ * \param EXCLUDE_HEADERS List of header files to be excluded from pre-parsed list of expected header files (e.g. nested messages that are not supported by QtProtobuf generator)
+ * \param PROTO_FILES List of .proto files that will be used in generation procedure
+ * \param MULTI Enables multi-files generation mode. If provided in parameter list generator will create pair of header/source files for each message
+ *        \note multi-files generation mode is defined as deprecated by QtProtobuf team, and might have poor support in future
+ * \param QML Enables QML code generation in protobuf classes. If provided in parameter list QML related code for lists and QML registration to be generated.
+ * \param COMMENTS Enables comments copying from .proto files. If provided in parameter list message and field related comments will be copied to generated header files.
+ *
+ *
+ * \subsection cmake_qtprotobuf_link_archive qtprotobuf_link_archive
+ *
+ * \brief qtprotobuf_link_archive is cmake helper function that links whole archive to your library or executable target.
+ *
+ * \details It's useful when you try to link generated target to shared library or/and to executable that doesn't utilize all protobuf generated classes directly from C++ code, but requires them from QML.
+ *
+ * \param TARGET name of target to link to
+ * \param GENERATED_TARGET protobuf generated target name
+ *
+ * \section qmake
+ *  - \ref qmake_qtprotobuf_generate
+ *
+ * \subsection qmake_qtprotobuf_generate qtprotobuf_generate
+ *
+ * \brief qtprotobuf_generate is qmake helper <a href="https://doc.qt.io/qt-5/qmake-language.html#test-functions">test function</a> that generates QtProtobuf source code based on files provided by PROTO_FILES global context variable
+ * \param generate_qml generate_qml enables/disables QML code generation in protobuf classes. If set to `true` QML-related code for lists and QML registration to be generated.
+ */
+
 /*!
  * \ingroup generator
  * \private

src/generator/main.cpp

@@ -37,6 +37,12 @@
  *
  * QtProtobuf distributed in terms of MIT license and is free for modification and use under MIT
  * license <a href="https://github.com/semlanik/qtprotobuf/blob/master/LICENSE">terms</a>.
+ *
+ * QtProtobuf has 4 modules:
+ *  - \ref generator
+ *  - \ref QtProtobuf
+ *  - \ref QtGrpc
+ *  - \ref QtProtobufWellKnownTypes
  */
 using namespace ::QtProtobuf::generator;
 int main(int argc, char *argv[])

src/wellknowntypes/CMakeLists.txt

@@ -21,13 +21,7 @@ include(${QT_PROTOBUF_CMAKE_DIR}/GenerateQtHeaders.cmake)
 include(${QT_PROTOBUF_CMAKE_DIR}/QtProtobufGen.cmake)
 
 file(GLOB SOURCES
-    timestamp.qpb.cpp)
-
-file(GLOB HEADERS
-    qtprotobufwellknowntypes_global.qbp.h)
-
-file(GLOB PUBLIC_HEADER
-    qtprotobufwellknowntypes_global.qbp.h)
+    dummy.cpp)
 
 function(add_wellknowntype TYPENAME)
     list(APPEND LOOKUP_DIRS ${QT_PROTOBUF_SOURCE_DIR}/3rdparty/grpc/third_party/protobuf/src)

src/wellknowntypes/dummy.cpp

@@ -0,0 +1,100 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2020 Alexey Edelev <semlanik@gmail.com>
+ *
+ * This file is part of qtprotobuf project https://git.semlanik.org/semlanik/qtprotobuf
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this
+ * software and associated documentation files (the "Software"), to deal in the Software
+ * without restriction, including without limitation the rights to use, copy, modify,
+ * merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+ * to permit persons to whom the Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies
+ * or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+ * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+ * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+/*
+ * Well known types library consists of scope of autogenerated static libraries. This file is
+ * dummy placeholder to make add_library call possible.
+ */
+
+/*!
+ * \defgroup QtProtobufWellKnownTypes
+ * \brief Google Protobuf Well-Known types library for QtProtobuf
+ *
+ * \details QtProtobufWellKnownTypes contains follwing <a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf">Protobuf Well-Known types</a>:
+ *    - Any
+ *    - Timestamp
+ *    - Struct
+ *    - Value
+ *    - ListValue
+ *    - SourceContext
+ *    - DoubleValue
+ *    - FloatValue
+ *    - Int64Value
+ *    - UInt64Value
+ *    - Int32Value
+ *    - UInt32Value
+ *    - BoolValue
+ *    - StringValue
+ *    - BytesValue
+ *    - Type
+ *    - Field
+ *    - Enum
+ *    - EnumValue
+ *    - Option
+ *    - Empty
+ *    - FieldMask
+ *    - Api
+ *    - Method
+ *    - Mixin
+ *    - Duration
+ *
+ *
+ * To use well-known type in your project you may include corresponding google .proto file in your interface:
+ *
+ * \code
+ * syntax = "proto3";
+ * package somepackage;
+ *
+ * import "google/protobuf/empty.proto";
+ * import "google/protobuf/timestamp.proto";
+ *
+ * message AnimationMessage {
+ *     uint32 animationId = 1;
+ *     google.protobuf.Timestamp startTime = 2;
+ *     google.protobuf.Timestamp endTime = 3;
+ * }
+ *
+ * service AnimationService {
+ *     rpc startAnimation(AnimationMessage) returns (google.protobuf.Empty) {}
+ * }
+ * \endcode
+ *
+ * It's also possible to use some of generated well-known types directly, simply include corresponding header:
+ *
+ * \code
+ * #include <google/protobuf/any.qpb.h>
+ * ...
+ *     google::protobuf::Any someAnyVariable;
+ *     someAnyVariable.setType_url("http://somedomain.org/someTypeDescription");
+ *     someAnyVariable.setValue(data);
+ * ...
+ * \endcode
+ *
+ * In both scenarious you also need to link QtProtobufWellKnownTypes library by adding following lines to
+ * **CMakeLists.txt** for your target.
+ * \code
+ *     target_link_libraries(YourTargetName PRIVATE QtProtobufProject::QtProtobufWellKnownTypes)
+ * \endcode
+ */

src/wellknowntypes/qtprotobufwellknowntypes_global.qbp.h

@@ -1,75 +0,0 @@
-/*
- * MIT License
- *
- * Copyright (c) 2019 Alexey Edelev <semlanik@gmail.com>
- *
- * This file is part of QtProtobuf project https://git.semlanik.org/semlanik/qtprotobuf
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy of this
- * software and associated documentation files (the "Software"), to deal in the Software
- * without restriction, including without limitation the rights to use, copy, modify,
- * merge, publish, distribute, sublicense, and/or sell copies of the Software, and
- * to permit persons to whom the Software is furnished to do so, subject to the following
- * conditions:
- *
- * The above copyright notice and this permission notice shall be included in all copies
- * or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
- * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
- * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
- * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
- * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
- * DEALINGS IN THE SOFTWARE.
- */
-
-#pragma once
-
-#include "google/protobuf/any.qpb.h"
-#include "google/protobuf/api.qpb.h"
-#include "google/protobuf/duration.qpb.h"
-#include "google/protobuf/empty.qpb.h"
-#include "google/protobuf/field_mask.qpb.h"
-#include "google/protobuf/source_context.qpb.h"
-#include "google/protobuf/struct.qpb.h"
-#include "google/protobuf/timestamp.qpb.h"
-#include "google/protobuf/type.qpb.h"
-#include "google/protobuf/wrappers.qpb.h"
-
-namespace google {
-
-namespace protobuf {
-
-inline void qRegisterProtobufTypes() {
-    NullValueGadget::registerTypes();
-    SyntaxGadget::registerTypes();
-    qRegisterProtobufType<Any>();
-    qRegisterProtobufType<Api>();
-    qRegisterProtobufType<Method>();
-    qRegisterProtobufType<Mixin>();
-    qRegisterProtobufType<Duration>();
-    qRegisterProtobufType<Empty>();
-    qRegisterProtobufType<FieldMask>();
-    qRegisterProtobufType<SourceContext>();
-    qRegisterProtobufType<Struct>();
-    qRegisterProtobufType<Value>();
-    qRegisterProtobufType<ListValue>();
-    qRegisterProtobufType<Timestamp>();
-    qRegisterProtobufType<Type>();
-    qRegisterProtobufType<Field>();
-    qRegisterProtobufType<Enum>();
-    qRegisterProtobufType<EnumValue>();
-    qRegisterProtobufType<Option>();
-    qRegisterProtobufType<DoubleValue>();
-    qRegisterProtobufType<FloatValue>();
-    qRegisterProtobufType<Int64Value>();
-    qRegisterProtobufType<UInt64Value>();
-    qRegisterProtobufType<Int32Value>();
-    qRegisterProtobufType<UInt32Value>();
-    qRegisterProtobufType<StringValue>();
-    qRegisterProtobufType<BytesValue>();
-}
-
-}
-
-}

tests/test_wellknowntypes/simpletest.cpp

@@ -32,8 +32,16 @@
 #include <stdio.h>
 #include <iostream>
 #include <gtest/gtest.h>
+#include <google/protobuf/any.qpb.h>
+#include <google/protobuf/api.qpb.h>
+#include <google/protobuf/type.qpb.h>
+#include <google/protobuf/struct.qpb.h>
+#include <google/protobuf/empty.qpb.h>
+#include <google/protobuf/duration.qpb.h>
+#include <google/protobuf/wrappers.qpb.h>
+#include <google/protobuf/field_mask.qpb.h>
+
 #include "wellknowntypes.qpb.h"
-#include <qtprotobufwellknowntypes_global.qbp.h>
 
 using namespace google::protobuf;
 
@@ -62,7 +70,6 @@ public:
 
     static void SetUpTestCase() {
         QtProtobuf::qRegisterProtobufTypes();
-        google::protobuf::qRegisterProtobufTypes();
         serializer.reset(new QProtobufSerializer);
     }