Update doxygen documentation as well as tutorial

CMakeLists.txt

@@ -133,7 +133,7 @@ endif()
 # DOCUMENTATION
 #----------------------------------
 
-option(BUILD_DOC "Build documentation" ON)
+option(BUILD_DOC "Build doxygen documentation for sdbus-c++ API" ON)
 
 if(BUILD_DOC)
     add_subdirectory("${CMAKE_SOURCE_DIR}/doc")

README.md

@@ -20,23 +20,27 @@ $ sudo make install
 
 * `BUILD_CODE_GEN` [boolean]
 
-  Option for building the stub code generator `sdbus-c++-xml2cpp` for generating the adaptor and proxy interfaces out of the D-Bus IDL XML description. `OFF` by default. Use `-DBUILD_CODE_GEN=ON` flag to turn on building the code gen.
+  Option for building the stub code generator `sdbus-c++-xml2cpp` for generating the adaptor and proxy interfaces out of the D-Bus IDL XML description. Default value: `OFF`. Use `-DBUILD_CODE_GEN=ON` flag to turn on building the code gen.
+
+* `BUILD_DOC` [boolean]
+
+  Option for building Doxygen documentation of sdbus-c++ API. If `BUILD_DOC` is enabled, the documentation must still be built explicitly through `make doc`. Default value: `ON`. Use `-DBUILD_DOC=OFF` to disable searching for Doxygen and building Doxygen documentation of sdbus-c++ API.
 
 * `BUILD_TESTS` [boolean]
 
-  Option for building sdbus-c++ unit and integration tests, invokable by `make test`. That incorporates downloading and building static libraries of Google Test. `OFF` by default. Use `-DBUILD_TESTS=ON` to enable building the tests. With this option turned on, you may also enable/disable the following options:
+  Option for building sdbus-c++ unit and integration tests, invokable by `make test`. That incorporates downloading and building static libraries of Google Test. Default value: `OFF`. Use `-DBUILD_TESTS=ON` to enable building the tests. With this option turned on, you may also enable/disable the following options:
 
     * `BUILD_PERF_TESTS` [boolean]
 
-      Option for building sdbus-c++ performance tests. `OFF` by default.
+      Option for building sdbus-c++ performance tests. Default value: `OFF`.
 
     * `BUILD_STRESS_TESTS` [boolean]
 
-      Option for building sdbus-c++ stress tests. `OFF` by default.
+      Option for building sdbus-c++ stress tests. Default value: `OFF`.
 
     * `TESTS_INSTALL_PATH` [string]
 
-      Path where the test binaries shall get installed. Set to `/opt/test/bin` by default.
+      Path where the test binaries shall get installed. Default value: `/opt/test/bin`.
 
 Dependencies
 ------------

include/sdbus-c++/IConnection.h

@@ -38,8 +38,8 @@ namespace sdbus {
      * An interface to D-Bus bus connection. Incorporates implementation
      * of both synchronous and asynchronous processing loop.
      *
-     * All methods throw @sdbus::Error in case of failure. The class is
+     * All methods throw sdbus::Error in case of failure. All methods in
-     * thread-aware, but not thread-safe.
+     * this class are thread-aware, but not thread-safe.
      *
      ***********************************************/
     class IConnection
@@ -67,7 +67,7 @@ namespace sdbus {
         * @brief Enters the D-Bus processing loop
         *
         * The incoming D-Bus messages are processed in the loop. The method
-        * blocks indefinitely, until unblocked via @leaveProcessingLoop.
+        * blocks indefinitely, until unblocked via leaveProcessingLoop.
         *
         * @throws sdbus::Error in case of failure
         */
@@ -76,7 +76,7 @@ namespace sdbus {
         /*!
         * @brief Enters the D-Bus processing loop in a separate thread
         *
-        * The same as @enterProcessingLoop, except that it doesn't block
+        * The same as enterProcessingLoop, except that it doesn't block
         * because it runs the loop in a separate thread managed internally.
         */
         virtual void enterProcessingLoopAsync() = 0;

include/sdbus-c++/IObject.h

@@ -47,8 +47,11 @@ namespace sdbus {
      * An interface to D-Bus object. Provides API for registration
      * of methods, signals, properties, and for emitting signals.
      *
-     * All methods throw @c sdbus::Error in case of failure. The class is
+     * All methods throw @c sdbus::Error in case of failure.
-     * thread-aware, but not thread-safe.
+     * In general, the class is thread-aware, but not thread-safe.
+     * However, the operation of creating and sending asynchronous
+     * method replies, as well as creating and emitting
+     * signals, is thread-safe.
      *
      ***********************************************/
     class IObject
@@ -62,7 +65,7 @@ namespace sdbus {
         * @param[in] inputSignature D-Bus signature of method input parameters
         * @param[in] outputSignature D-Bus signature of method output parameters
         * @param[in] methodCallback Callback that implements the body of the method
-        * @param[in] noReply If true, the method isn't expected to send reply
+        * @param[in] flags D-Bus method flags (privileged, deprecated, or no reply)
         *
         * @throws sdbus::Error in case of failure
         */
@@ -81,7 +84,7 @@ namespace sdbus {
         * @param[in] inputSignature D-Bus signature of method input parameters
         * @param[in] outputSignature D-Bus signature of method output parameters
         * @param[in] asyncMethodCallback Callback that implements the body of the method
-        * @param[in] noReply If true, the method isn't expected to send reply
+        * @param[in] flags D-Bus method flags (privileged, deprecated, or no reply)
         *
         * This overload register a method callback that will have a freedom to execute
         * its body in asynchronous contexts, and send the results from those contexts.
@@ -103,6 +106,7 @@ namespace sdbus {
         * @param[in] interfaceName Name of an interface that the signal will fall under
         * @param[in] signalName Name of the signal
         * @param[in] signature D-Bus signature of signal parameters
+        * @param[in] flags D-Bus signal flags (deprecated)
         *
         * @throws sdbus::Error in case of failure
         */
@@ -118,6 +122,7 @@ namespace sdbus {
         * @param[in] propertyName Name of the property
         * @param[in] signature D-Bus signature of property parameters
         * @param[in] getCallback Callback that implements the body of the property getter
+        * @param[in] flags D-Bus property flags (deprecated, property update behavior)
         *
         * @throws sdbus::Error in case of failure
         */
@@ -135,6 +140,7 @@ namespace sdbus {
         * @param[in] signature D-Bus signature of property parameters
         * @param[in] getCallback Callback that implements the body of the property getter
         * @param[in] setCallback Callback that implements the body of the property setter
+        * @param[in] flags D-Bus property flags (deprecated, property update behavior)
         *
         * @throws sdbus::Error in case of failure
         */
@@ -327,6 +333,9 @@ namespace sdbus {
     * The provided connection will be used by the object to export methods,
     * issue signals and provide properties.
     *
+    * Creating a D-Bus object instance is (thread-)safe even upon the connection
+    * which is already running its processing loop.
+    *
     * Code example:
     * @code
     * auto proxy = sdbus::createObject(connection, "/com/kistler/foo");

include/sdbus-c++/IObjectProxy.h

@@ -47,8 +47,10 @@ namespace sdbus {
      * An interface to D-Bus object proxy. Provides API for calling
      * methods, getting/setting properties, and for registering to signals.
      *
-     * All methods throw @c sdbus::Error in case of failure. The class is
+     * All methods throw @c sdbus::Error in case of failure.
-     * thread-aware, but not thread-safe.
+     * In general, the class is thread-aware, but not thread-safe.
+     * However, the operation of creating and sending method calls
+     * (both synchronously and asynchronously) is thread-safe.
      *
      ***********************************************/
     class IObjectProxy
@@ -107,7 +109,7 @@ namespace sdbus {
         * @brief Calls method on the proxied D-Bus object asynchronously
         *
         * @param[in] message Message representing an async method call
-        * @param[in] asyncReplyHandler Handler for the async reply
+        * @param[in] asyncReplyCallback Handler for the async reply
         *
         * The call is non-blocking. It doesn't wait for the reply. Once the reply arrives,
         * the provided async reply handler will get invoked from the context of the connection
@@ -284,11 +286,10 @@ namespace sdbus {
     * @return Pointer to the object proxy instance
     *
     * The provided connection will be used by the proxy to issue calls against the object,
-    * and signals, if any, will be subscribed to on this connection. Since the caller still
+    * and signals, if any, will be subscribed to on this connection. The caller still
-    * remains the owner of the connection (the proxy just keeps reference to it) after the call,
+    * remains the owner of the connection (the proxy just keeps a reference to it), and
-    * the proxy will not start its own background processing loop for incoming signals (if any),
+    * should make sure that a processing loop is running on that connection, so the proxy
-    * as it will rely on the client as an owner of the connection to handle processing of
+    * may receive incoming signals and asynchronous method replies.
-    * incoming messages on that connection by themselves.
     *
     * Code example:
     * @code
@@ -308,11 +309,10 @@ namespace sdbus {
     * @return Pointer to the object proxy instance
     *
     * The provided connection will be used by the proxy to issue calls against the object,
-    * and signals, if any, will be subscribed to on this connection. Object proxy becomes
+    * and signals, if any, will be subscribed to on this connection. The Object proxy becomes
-    * an exclusive owner of this connection. The effect of this is that when there is at
+    * an exclusive owner of this connection, and will automatically start a procesing loop
-    * least one signal in proxy's interface, then the proxy will immediately start its own
+    * upon that connection in a separate internal thread. Handlers for incoming signals and
-    * processing loop for this connection in a separate internal thread, causing incoming
+    * asynchronous method replies will be executed in the context of that thread.
-    * signals to be correctly received and processed in the context of that internal thread.
     *
     * Code example:
     * @code
@@ -330,14 +330,14 @@ namespace sdbus {
     * @param[in] objectPath Path of the D-Bus object
     * @return Pointer to the object proxy instance
     *
-    * This factory overload creates a proxy that manages its own D-Bus connection(s).
+    * No D-Bus connection is provided here, so the object proxy will create and manage
-    * When there is at least one signal in proxy's interface, then the proxy will immediately
+    * his own connection, and will automatically start a procesing loop upon that connection
-    * start its own processing loop for this connection in its own separate thread, causing
+    * in a separate internal thread. Handlers for incoming signals and asynchronous
-    * incoming signals to be correctly received and processed in the context of that thread.
+    * method replies will be executed in the context of that thread.
     *
     * Code example:
     * @code
-    * auto proxy = sdbus::createObjectProxy(connection, "com.kistler.foo", "/com/kistler/foo");
+    * auto proxy = sdbus::createObjectProxy("com.kistler.foo", "/com/kistler/foo");
     * @endcode
     */
     std::unique_ptr<sdbus::IObjectProxy> createObjectProxy( std::string destination