Documentation: Add / Fix documentation. (#1179)

contrib/ecalhdf5/include/ecalhdf5/eh5_meas.h

@@ -63,15 +63,21 @@ namespace eCAL
       ~HDF5Meas();
 
       /**
-       * @brief Copy operator
+       * @brief Copy constructor deleted
       **/
       HDF5Meas(const HDF5Meas& other) = delete;
+      /**
+       * @brief Move assignemnt deleted
+      **/
       HDF5Meas& operator=(const HDF5Meas& other) = delete;
 
       /**
-      * @brief Move operator
+      * @brief Move constructor
       **/
       HDF5Meas(HDF5Meas&&) = default;
+      /**
+       * @brief Move assignment
+      **/
       HDF5Meas& operator=(HDF5Meas&&) = default;
 
       /**

contrib/ecalhdf5/include/ecalhdf5/eh5_types.h

@@ -39,7 +39,6 @@ namespace eCAL
     const std::string kFileVerAttrTitle   ("Version");
     const std::string kTimestampAttrTitle ("Timestamps");
     const std::string kChnAttrTitle       ("Channels");
-    //!< @endcond
 
     /**
      * @brief Info struct for a single measurement entry

doc/CMakeLists.txt

@@ -99,6 +99,7 @@ set(DOXYGEN_FILE_PATTERNS        "*.h")
 set(DOXYGEN_RECURSIVE            NO)
 set(DOXYGEN_OUTPUT_DIRECTORY     ${DOC_SOURCE_DIRECTORY})
 set(DOXYGEN_XML_OUTPUT           ${DOC_SOURCE_DIRECTORY}/_doxygen)
+set(DOXYGEN_DISTRIBUTE_GROUP_DOC NO)
 
 # Allow @experimental to be used in headers to mark an API as experimental and add it to a list of
 # experimental APIs.

ecal/core/include/ecal/ecal_config.h

@@ -25,6 +25,7 @@
 
 #include <string>
 
+//@{ 
 namespace eCAL
 {
   namespace Config
@@ -133,3 +134,4 @@ namespace eCAL
     }
   }
 }
+//@}

ecal/core/include/ecal/ecal_deprecate.h

@@ -27,32 +27,32 @@
 #include <ecal/ecal_defs.h>
 
 #if ECAL_VERSION_INTEGER >= ECAL_VERSION_CALCULATE(5, 4, 0)
-#define ECAL_DEPRECATE_SINCE_5_4(__message__) [[deprecated(__message__)]]
+#define ECAL_DEPRECATE_SINCE_5_4(__message__) [[deprecated(__message__)]] //!< Deprecate the following function with eCAL Version 5.4.0
 #else 
-#define ECAL_DEPRECATE_SINCE_5_4(__message__)
+#define ECAL_DEPRECATE_SINCE_5_4(__message__)                             //!< Deprecate the following function with eCAL Version 5.4.0
 #endif
 
 
 #if ECAL_VERSION_INTEGER >= ECAL_VERSION_CALCULATE(5, 10, 0)
-#define ECAL_DEPRECATE_SINCE_5_10(__message__) [[deprecated(__message__)]]
+#define ECAL_DEPRECATE_SINCE_5_10(__message__) [[deprecated(__message__)]] //!< Deprecate the following function with eCAL Version 5.10.0
 #else 
-#define ECAL_DEPRECATE_SINCE_5_10(__message__)
+#define ECAL_DEPRECATE_SINCE_5_10(__message__)                             //!< Deprecate the following function with eCAL Version 5.10.0
 #endif
 
 #if ECAL_VERSION_INTEGER >= ECAL_VERSION_CALCULATE(5, 11, 0)
-#define ECAL_DEPRECATE_SINCE_5_11(__message__) [[deprecated(__message__)]]
+#define ECAL_DEPRECATE_SINCE_5_11(__message__) [[deprecated(__message__)]] //!< Deprecate the following function with eCAL Version 5.11.0
 #else 
-#define ECAL_DEPRECATE_SINCE_5_11(__message__)
+#define ECAL_DEPRECATE_SINCE_5_11(__message__)                             //!< Deprecate the following function with eCAL Version 5.11.0
 #endif
 
 #if ECAL_VERSION_INTEGER >= ECAL_VERSION_CALCULATE(5, 12, 0)
-#define ECAL_DEPRECATE_SINCE_5_12(__message__) [[deprecated(__message__)]]
+#define ECAL_DEPRECATE_SINCE_5_12(__message__) [[deprecated(__message__)]] //!< Deprecate the following function with eCAL Version 5.12.0
 #else 
-#define ECAL_DEPRECATE_SINCE_5_12(__message__)
+#define ECAL_DEPRECATE_SINCE_5_12(__message__)                             //!< Deprecate the following function with eCAL Version 5.12.0
 #endif
 
 #if ECAL_VERSION_INTEGER >= ECAL_VERSION_CALCULATE(5, 13, 0)
-#define ECAL_DEPRECATE_SINCE_5_13(__message__) [[deprecated(__message__)]]
+#define ECAL_DEPRECATE_SINCE_5_13(__message__) [[deprecated(__message__)]] //!< Deprecate the following function with eCAL Version 5.13.0
 #else 
-#define ECAL_DEPRECATE_SINCE_5_13(__message__)
+#define ECAL_DEPRECATE_SINCE_5_13(__message__)                             //!< Deprecate the following function with eCAL Version 5.13.0
 #endif

ecal/core/include/ecal/ecal_log_level.h

@@ -41,7 +41,4 @@ enum eCAL_Logging_eLogLevel
   log_level_debug4  = 128,
 };
 
-/*
-* @brief This type is to be used as a bitmask for the activated logging levels
-*/
-typedef char eCAL_Logging_Filter;
+typedef char eCAL_Logging_Filter;  //!< This type is to be used as a bitmask for the activated logging levels

ecal/core/include/ecal/ecal_publisher.h

@@ -71,8 +71,8 @@ namespace eCAL
   {
   public:
 
-    ECAL_API static constexpr long long DEFAULT_TIME_ARGUMENT        = -1;
-    ECAL_API static constexpr long long DEFAULT_ACKNOWLEDGE_ARGUMENT = -1;
+    ECAL_API static constexpr long long DEFAULT_TIME_ARGUMENT        = -1;  /*!< Use DEFAULT_TIME_ARGUMENT in the `Send()` function to let eCAL determine the send timestamp */
+    ECAL_API static constexpr long long DEFAULT_ACKNOWLEDGE_ARGUMENT = -1;  /*!< Use DEFAULT_ACKNOWLEDGE_ARGUMENT in the `Send()` function to let eCAL determine from configuration if the send operation needs to be acknowledged. */
 
     /**
      * @brief Constructor. 
@@ -101,7 +101,6 @@ namespace eCAL
     * @brief Constructor.
     *
     * @param topic_name_   Unique topic name.
-    * @param topic_info_   Topic information (encoding, type, descriptor)
     **/
     ECAL_API CPublisher(const std::string& topic_name_);
 
@@ -156,7 +155,6 @@ namespace eCAL
      * @brief Creates this object.
      *
      * @param topic_name_   Unique topic name.
-     * @param topic_info_   Topic information (encoding, type, descriptor)
      *
      * @return  True if it succeeds, false if it fails.
     **/

ecal/core/include/ecal/ecal_types.h

@@ -18,7 +18,7 @@
 */
 
 /**
- * @file   topic_information.h
+ * @file   ecal_types.h
  * @brief  This file contains type definitions for information associated with a given topic
 **/
 
@@ -37,6 +37,7 @@ namespace eCAL
       std::string encoding;      //!< encoding of the datatype (e.g. protobuf, flatbuffers, capnproto)
       std::string descriptor;    //!< descriptor information of the datatype (necessary for reflection)
 
+      //!< @cond
       bool operator==(const SDataTypeInformation& other) const
       {
         return name == other.name && encoding == other.encoding && descriptor == other.descriptor;
@@ -46,6 +47,7 @@ namespace eCAL
       {
         return !(*this == other);
       }
+      //!< @endcond
     };
 
     /**
@@ -56,6 +58,7 @@ namespace eCAL
     {
       SDataTypeInformation topic_type; //!< Data type description of the topic
 
+      //!< @cond
       bool operator==(const STopicInformation& other) const
       {
         return topic_type == other.topic_type;
@@ -65,6 +68,7 @@ namespace eCAL
       {
         return !(*this == other);
       }
+      //!< @endcond
     };
 
     /**
@@ -76,6 +80,7 @@ namespace eCAL
       SDataTypeInformation request_type;   //!< Data type description of the request
       SDataTypeInformation response_type;  //!< Data type description of the response
 
+      //!< @cond
       bool operator==(const SServiceMethodInformation& other) const
       {
         return request_type == other.request_type && response_type == other.response_type;
@@ -85,6 +90,7 @@ namespace eCAL
       {
         return !(*this == other);
       }
+      //!< @endcond
     };
 
 }

ecal/core/include/ecal/ecal_util.h

@@ -18,7 +18,7 @@
 */
 
 /**
- * @file   ecal_util.h
+ * @file   
  * @brief  eCAL utility interface
 **/
 
@@ -35,6 +35,7 @@
 #include <tuple>
 #include <vector>
 
+
 namespace eCAL
 {
   namespace Util
@@ -166,7 +167,7 @@ namespace eCAL
      *
      * @return  True if succeeded.
     **/
-    ECAL_DEPRECATE_SINCE_5_13("Please use the method bool GetDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
+    ECAL_DEPRECATE_SINCE_5_13("Please use the method bool GetTopicDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
     ECAL_API bool GetTopicTypeName(const std::string& topic_name_, std::string& topic_type_);
 
     /**
@@ -176,7 +177,7 @@ namespace eCAL
      *
      * @return  Topic type name.
     **/
-    ECAL_DEPRECATE_SINCE_5_13("Please use the method bool GetDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
+    ECAL_DEPRECATE_SINCE_5_13("Please use the method bool GetTopicDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
     ECAL_API std::string GetTopicTypeName(const std::string& topic_name_);
 
     /**
@@ -187,7 +188,7 @@ namespace eCAL
      *
      * @return  True if succeeded.
     **/
-    ECAL_DEPRECATE_SINCE_5_13("Please use the method bool GetDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the descriptor from the STopicInformation variable. This function will be removed in eCAL6.")
+    ECAL_DEPRECATE_SINCE_5_13("Please use the method bool GetTopicDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the descriptor from the STopicInformation variable. This function will be removed in eCAL6.")
     ECAL_API bool GetTopicDescription(const std::string& topic_name_, std::string& topic_desc_);
 
     /**
@@ -197,7 +198,7 @@ namespace eCAL
      *
      * @return  Topic description.
     **/
-    ECAL_DEPRECATE_SINCE_5_13("Please use the method bool GetDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the descriptor from the STopicInformation variable. This function will be removed in eCAL6.")
+    ECAL_DEPRECATE_SINCE_5_13("Please use the method bool GetTopicDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the descriptor from the STopicInformation variable. This function will be removed in eCAL6.")
     ECAL_API std::string GetTopicDescription(const std::string& topic_name_);
 
     /**
@@ -252,39 +253,39 @@ namespace eCAL
     /**
      * @brief Gets type name of the specified topic.
      * 
-     * This function is deprecated with eCAL 5.10. Please use GetDataTypeInformation.
+     * This function is deprecated with eCAL 5.10. Please use GetTopicDataTypeInformation.
      *
      * @param topic_name_   Topic name.
      * @param topic_type_   String to store type name.
      *
      * @return  True if succeeded.
     **/
-    ECAL_DEPRECATE_SINCE_5_10("Please use the method bool GetDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
+    ECAL_DEPRECATE_SINCE_5_10("Please use the method bool GetTopicDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
     ECAL_API bool GetTypeName(const std::string& topic_name_, std::string& topic_type_);
 
     /**
      * @brief Gets type name of the specified topic.
      *
-     * This function is deprecated with eCAL 5.10. Please use GetDataTypeInformation.
+     * This function is deprecated with eCAL 5.10. Please use GetTopicDataTypeInformation.
      *
      * @param topic_name_   Topic name.
      *
      * @return  Topic type name.
     **/
-    ECAL_DEPRECATE_SINCE_5_10("Please use the method bool GetDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
+    ECAL_DEPRECATE_SINCE_5_10("Please use the method bool GetTopicDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
     ECAL_API std::string GetTypeName(const std::string& topic_name_);
 
     /**
      * @brief Gets description of the specified topic.
      *
-     * This function is deprecated with eCAL 5.10. Please use GetDataTypeInformation.
+     * This function is deprecated with eCAL 5.10. Please use GetTopicDataTypeInformation.
      *
      * @param topic_name_   Topic name.
      * @param topic_desc_   String to store description.
      *
      * @return  True if succeeded.
     **/
-    ECAL_DEPRECATE_SINCE_5_10("Please use the method bool GetDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
+    ECAL_DEPRECATE_SINCE_5_10("Please use the method bool GetTopicDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
     ECAL_API bool GetDescription(const std::string& topic_name_, std::string& topic_desc_);
 
     /**
@@ -296,13 +297,13 @@ namespace eCAL
      *
      * @return  Topic description.
     **/
-    ECAL_DEPRECATE_SINCE_5_13("Please use the method bool GetDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
+    ECAL_DEPRECATE_SINCE_5_13("Please use the method bool GetTopicDataTypeInformation(const std::string& topic_name_, SDataTypeInformation& topic_info_) instead. You can extract the type information from the members encoding and type of the STopicInformation variable. This function will be removed in eCAL6.")
     ECAL_API std::string GetDescription(const std::string& topic_name_);
 
     /**
     * @brief Splits the topic type (eCAL < 5.12) into encoding and types (>= eCAL 5.12)
     *
-    * @param topictype_name_   "Old" typename.
+    * @param combined_topic_type_  "Old" typename.
     *
     * @return  std::pair(encoding, typename).
     **/
@@ -317,6 +318,5 @@ namespace eCAL
     * @return "Old" typename. ( encoding:typename ).
     **/
     ECAL_API std::string CombinedTopicEncodingAndType(const std::string& topic_encoding_, const std::string& topic_type_);
-
   }
 }

ecal/core/include/ecal/msg/publisher.h

@@ -47,28 +47,44 @@ namespace eCAL
   {
   public:
     /**
-     * @brief  Constructor. 
+     * @brief  Default Constructor. 
+     *         Using this constructor, the object is not actually in a usable state.
+     *         Before being able to send data, one has to call the `Create()` function, first.
     **/
     CMsgPublisher() : CPublisher()
     {
     }
 
     /**
-     * @brief  Constructor. 
+     * @brief  Constructor, that automatically intializes the Publisher. 
+     *         This function will be deprecated with eCAL 5.13, please use one of other constructors instead.
      *
      * @param topic_name_  Unique topic name. 
-     * @param topic_type_  Type name (optional for type checking). 
+     * @param topic_type_  Type name. 
      * @param topic_desc_  Type description (optional for description checking). 
     **/
     ECAL_DEPRECATE_SINCE_5_13("Please use the constructor CMsgPublisher(const std::string& topic_name_, const SDataTypeInformation& topic_info_) instead. This function will be removed in eCAL6. ")
     CMsgPublisher(const std::string& topic_name_, const std::string& topic_type_, const std::string& topic_desc_ = "") : CPublisher(topic_name_, topic_type_, topic_desc_)
     {
     }
 
+    /**
+     * @brief  Constructor, that automatically intializes the Publisher. 
+     *         This should be the preferred constructor.
+     *
+     * @param topic_name_  Unique topic name.
+     * @param topic_info_  Struct that contains information of the datatype (name, encoding, description) of the topic.
+     **/
     CMsgPublisher(const std::string& topic_name_, const SDataTypeInformation& topic_info_) : CPublisher(topic_name_, topic_info_)
     {
     }
 
+    /**
+     * @brief  Constructor, that automatically intializes the Publisher. 
+     *         If no datatype information about the topic is available, this constructor can be used.
+     *
+     * @param topic_name_  Unique topic name.
+     **/
     CMsgPublisher(const std::string& topic_name_) : CMsgPublisher(topic_name_, GetDataTypeInformation())
     {
     }