From 489556d3111de880129525199dd9b84f9d614dd1 Mon Sep 17 00:00:00 2001
From: florian <f.spreckelsen@inidscale.com>
Date: Mon, 2 Aug 2021 10:47:44 +0200
Subject: [PATCH] WIP: Merge manually

---
 CMakeLists.txt                      |  2 +-
 DEPENDENCIES.md                     |  4 +--
 include/caosdb/connection.h         |  3 ++
 include/caosdb/entity.h             |  2 ++
 include/caosdb/exceptions.h         | 34 ++++++++---------------
 include/caosdb/log_level.h          |  4 +--
 include/caosdb/logging.h            | 43 +++++++++++++++++++++++++----
 include/caosdb/message_code.h       | 10 +++++--
 include/caosdb/transaction_status.h | 11 ++++++--
 src/caosdb/configuration.cpp        |  8 ++++--
 src/caosdb/logging.cpp              |  7 +++++
 11 files changed, 86 insertions(+), 42 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index f61fbe5..b71dca2 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -31,7 +31,7 @@ project(libcaosdb
     DESCRIPTION "C and C++ client libraries for CaosDB"
     LANGUAGES CXX C)
 
-set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD 99)
 set(CMAKE_CXX_STANDARD 17)
 
 set(CMAKE_C_EXTENSIONS OFF)
diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md
index 7a8c012..63a0678 100644
--- a/DEPENDENCIES.md
+++ b/DEPENDENCIES.md
@@ -1,7 +1,7 @@
 # GENERAL
 
-* >=conan-1.37.2 (e.g. with `pip install conan`)
-* >=cmake-3.14
+* >=conan-1.37.2
+* >=cmake-3.13
 * >=gcc-10.2.0 | >=clang-11
 
 # OPTIONAL
diff --git a/include/caosdb/connection.h b/include/caosdb/connection.h
index 22bdc6f..5d7930a 100644
--- a/include/caosdb/connection.h
+++ b/include/caosdb/connection.h
@@ -149,6 +149,9 @@ public:
     return ConnectionManager::GetInstance().mGetConnection(name);
   };
 
+  /**
+   * Get the connection marked by the "default" key in the configuration.
+   */
   inline static auto GetDefaultConnection()
     -> const std::shared_ptr<Connection> & {
     return ConnectionManager::GetInstance().mGetDefaultConnection();
diff --git a/include/caosdb/entity.h b/include/caosdb/entity.h
index 911f621..34f8d1b 100644
--- a/include/caosdb/entity.h
+++ b/include/caosdb/entity.h
@@ -213,6 +213,8 @@ private:
  *
  * This is a property which belongs to another entity. Don't confuse it with
  * an Entity with the "Property" role.
+ *
+ * @brief Property of an Entity.
  */
 class Property {
 public:
diff --git a/include/caosdb/exceptions.h b/include/caosdb/exceptions.h
index 6dc44cb..4653ed2 100644
--- a/include/caosdb/exceptions.h
+++ b/include/caosdb/exceptions.h
@@ -32,9 +32,9 @@ using std::runtime_error;
 /**
  * @brief Generic exception class of the caosdb client library.
  */
-class GenericException : public runtime_error {
+class Exception : public runtime_error {
 public:
-  explicit GenericException(StatusCode code, const std::string &what_arg)
+  explicit Exception(StatusCode code, const std::string &what_arg)
     : runtime_error(what_arg), code(code) {}
   [[nodiscard]] inline auto GetCode() const -> StatusCode { return this->code; }
 
@@ -45,57 +45,47 @@ private:
 /**
  * @brief Exception for authentication errors.
  */
-class AuthenticationError : public GenericException {
+class AuthenticationError : public Exception {
 public:
   explicit AuthenticationError(const std::string &what_arg)
-    : GenericException(StatusCode::AUTHENTICATION_ERROR, what_arg) {}
+    : Exception(StatusCode::AUTHENTICATION_ERROR, what_arg) {}
 };
 
 /**
  * @brief The connection to the CaosDB server is down.
  */
-class ConnectionError : public GenericException {
+class ConnectionError : public Exception {
 public:
   explicit ConnectionError(const std::string &what_arg)
-    : GenericException(StatusCode::CONNECTION_ERROR, what_arg) {}
+    : Exception(StatusCode::CONNECTION_ERROR, what_arg) {}
 };
 
 /**
  * @brief The transaction terminated unsuccessfully.
  */
-class TransactionError : public GenericException {
-protected:
-  TransactionError(StatusCode code, const std::string &what_arg)
-    : GenericException(code, what_arg) {}
-
+class TransactionError : public Exception {
 public:
   explicit TransactionError(const std::string &what_arg)
-    : GenericException(StatusCode::GENERIC_TRANSACTION_ERROR, what_arg) {}
-};
-
-class TransactionStatusError : public TransactionError {
-public:
-  explicit TransactionStatusError(const std::string &what_arg)
-    : TransactionError(StatusCode::TRANSACTION_STATUS_ERROR, what_arg) {}
+    : Exception(StatusCode::GENERIC_TRANSACTION_ERROR, what_arg) {}
 };
 
 /**
  * @brief Exception for errors of the ConfigurationManager or other components
  * of the configuration.
  */
-class ConfigurationError : public GenericException {
+class ConfigurationError : public Exception {
 public:
   explicit ConfigurationError(const std::string &what_arg)
-    : GenericException(StatusCode::CONFIGURATION_ERROR, what_arg) {}
+    : Exception(StatusCode::CONFIGURATION_ERROR, what_arg) {}
 };
 
 /**
  * @brief The connection isn't known to the ConnectionManager under this name.
  */
-class UnknownConnectionError : public GenericException {
+class UnknownConnectionError : public Exception {
 public:
   explicit UnknownConnectionError(const std::string &what_arg)
-    : GenericException(StatusCode::UNKNOWN_CONNECTION_ERROR, what_arg) {}
+    : Exception(StatusCode::UNKNOWN_CONNECTION_ERROR, what_arg) {}
 };
 
 } // namespace caosdb::exceptions
diff --git a/include/caosdb/log_level.h b/include/caosdb/log_level.h
index af05d3b..c2fcb9b 100644
--- a/include/caosdb/log_level.h
+++ b/include/caosdb/log_level.h
@@ -19,8 +19,8 @@
  *
  */
 
-#ifndef CAOSDB_LOG_LEVELS_H
-#define CAOSDB_LOG_LEVELS_H
+#ifndef CAOSDB_LOG_LEVEL_H
+#define CAOSDB_LOG_LEVEL_H
 
 #define CAOSDB_LOG_LEVEL_OFF 1000000
 #define CAOSDB_LOG_LEVEL_FATAL 700
diff --git a/include/caosdb/logging.h b/include/caosdb/logging.h
index 26ec1c8..fcebc6d 100644
--- a/include/caosdb/logging.h
+++ b/include/caosdb/logging.h
@@ -43,6 +43,9 @@ typedef boost::log::sources::severity_channel_logger<int, std::string>
 
 BOOST_LOG_INLINE_GLOBAL_LOGGER_DEFAULT(logger, boost_logger_class)
 
+/**
+ * This class stores the integer log level.
+ */
 class LevelConfiguration {
 public:
   LevelConfiguration(int level) : level(level){};
@@ -54,6 +57,11 @@ private:
 
 class SinkConfiguration;
 
+/**
+ * This class stores the logging level and log sinks.
+ *
+ * Sinks are represented by SinkConfiguration objects.
+ */
 class LoggingConfiguration : public LevelConfiguration {
 public:
   virtual ~LoggingConfiguration() = default;
@@ -69,6 +77,23 @@ private:
 auto initialize_logging_defaults() -> int;
 auto initialize_logging(const LoggingConfiguration &configuration) -> void;
 
+/**
+ * A logging sink is characterized by a name and destination.
+ *
+ * Typical inheriting configurations exist for console, files and syslog.
+ *
+ * When a SinkConfiguration is created from a configuration, the sink
+ * configuration must contain a \p destination key which matches one of the
+ * keywords for implemented sinks.  At the moment of writing this documentation,
+ * valid destinations are:
+ *
+ * \li \p file
+ * \li \p console
+ * \li \p syslog
+ *
+ * A \p level keyword sets the logging level, if it exists at the sink or
+ * logging level of the configuration.
+ */
 class SinkConfiguration : public LevelConfiguration {
 public:
   virtual ~SinkConfiguration() = default;
@@ -104,6 +129,12 @@ private:
   const std::string destination = "Console";
 };
 
+/**
+ * The file name is the destination, the directory can be set separately.
+ *
+ * If there is a `directory` key in the configuration, that will be used as a
+ * default, otherwise it is the current directory.
+ */
 class FileSinkConfiguration : public SinkConfiguration {
 public:
   virtual ~FileSinkConfiguration() = default;
@@ -136,27 +167,27 @@ private:
 };
 
 /**
- * Convenience function for the c-interface.
+ * Convenience function for the C interface.
  */
 void caosdb_log_fatal(const char *channel, const char *msg);
 /**
- * Convenience function for the c-interface.
+ * Convenience function for the C interface.
  */
 void caosdb_log_error(const char *channel, const char *msg);
 /**
- * Convenience function for the c-interface.
+ * Convenience function for the C interface.
  */
 void caosdb_log_warn(const char *channel, const char *msg);
 /**
- * Convenience function for the c-interface.
+ * Convenience function for the C interface.
  */
 void caosdb_log_info(const char *channel, const char *msg);
 /**
- * Convenience function for the c-interface.
+ * Convenience function for the C interface.
  */
 void caosdb_log_debug(const char *channel, const char *msg);
 /**
- * Convenience function for the c-interface.
+ * Convenience function for the C interface.
  */
 void caosdb_log_trace(const char *channel, const char *msg);
 
diff --git a/include/caosdb/message_code.h b/include/caosdb/message_code.h
index 17ec1c1..6f22c12 100644
--- a/include/caosdb/message_code.h
+++ b/include/caosdb/message_code.h
@@ -27,9 +27,13 @@
 /**
  * MessageCodes for entity messages.
  *
- * In contrast to the status codes, the message codes are part of the CaosDB
- * API. Messages (and their codes) represent the state of the entities in a
- * transaction or the server.
+ * In contrast to the status codes, the message codes are part of the
+ * CaosDB API. Messages (and their codes) represent the state of the
+ * entities in a transaction or the server.
+ *
+ * For a specification of the message codes, look at the protobuf
+ * documentation. The sources and documentation can be found at
+ * https://gitlab.indiscale.com/caosdb/src/caosdb-proto.
  */
 
 namespace caosdb::entity {
diff --git a/include/caosdb/transaction_status.h b/include/caosdb/transaction_status.h
index 8645ace..6c5b7a6 100644
--- a/include/caosdb/transaction_status.h
+++ b/include/caosdb/transaction_status.h
@@ -25,7 +25,12 @@
 /**
  * TransactionStatus indicates the current status of a transaction and, when it
  * has already terminated, whether the transaction has been successful or not.
+ *
+ * A status code of 0 denotes a generic success state, positive values indicate
+ * errors, and negative values indicate other states, such as different stages
+ * of a transaction in process.
  */
+
 #include "caosdb/status_code.h"
 #include "caosdb/exceptions.h"
 #include <memory> // for shared_ptr, unique_ptr
@@ -35,7 +40,7 @@ namespace caosdb::transaction {
 using caosdb::StatusCode;
 using caosdb::exceptions::AuthenticationError;
 using caosdb::exceptions::ConnectionError;
-using caosdb::exceptions::GenericException;
+using caosdb::exceptions::Exception;
 using caosdb::exceptions::TransactionError;
 
 /**
@@ -113,7 +118,7 @@ public:
     case StatusCode::GENERIC_TRANSACTION_ERROR:
       throw TransactionError(this->description);
     default:
-      throw GenericException(StatusCode::GENERIC_ERROR, this->description);
+      throw Exception(StatusCode::GENERIC_ERROR, this->description);
     }
   }
 
@@ -130,7 +135,7 @@ public:
   /**
    * Return a description of the erroneous state.
    *
-   * Returns an empty string if there is no description.
+   * No description yields an empty string.
    */
   inline auto GetDescription() const -> const std::string & {
     return this->description;
diff --git a/src/caosdb/configuration.cpp b/src/caosdb/configuration.cpp
index b3934d3..24e2790 100644
--- a/src/caosdb/configuration.cpp
+++ b/src/caosdb/configuration.cpp
@@ -358,7 +358,7 @@ auto ConfigurationManager::mReset() noexcept -> int {
     mClear();
     InitializeDefaults();
     return StatusCode::SUCCESS;
-  } catch (const caosdb::exceptions::GenericException &exc) {
+  } catch (const caosdb::exceptions::Exception &exc) {
     return exc.GetCode();
   } catch (const std::exception &exc) {
     CAOSDB_LOG_ERROR(logger_name)
@@ -373,7 +373,7 @@ auto ConfigurationManager::mClear() noexcept -> int {
     json_configuration = value(nullptr);
     ConnectionManager::Reset();
     return StatusCode::SUCCESS;
-  } catch (const caosdb::exceptions::GenericException &exc) {
+  } catch (const caosdb::exceptions::Exception &exc) {
     return exc.GetCode();
   } catch (const std::exception &exc) {
     CAOSDB_LOG_ERROR(logger_name)
@@ -468,7 +468,7 @@ auto ConfigurationManager::InitializeDefaults() -> int { // NOLINT
 
   // find the configuration file...
   std::unique_ptr<path> configuration_file_path;
-  for (const std::string &configuration_file :
+  for (const std::string configuration_file :
        caosdb::LIBCAOSDB_CONFIGURATION_FILES_PRECEDENCE) {
     if (configuration_file == "$CAOSDB_CLIENT_CONFIGURATION") {
       // user specified a file via the environment variable
@@ -508,9 +508,11 @@ auto ConfigurationManager::InitializeDefaults() -> int { // NOLINT
 
   // ... and use the configuration file
   if (configuration_file_path != nullptr) {
+    // TODO(tf): log which file has been used.
     mLoadSingleJSONConfiguration(*configuration_file_path);
   }
 
+  // Logging in the configuration leads to additional content.
   if (this->json_configuration.is_object() &&
       this->json_configuration.as_object().contains("logging")) {
     LoggingConfiguration logging_configuration =
diff --git a/src/caosdb/logging.cpp b/src/caosdb/logging.cpp
index 486ab84..3618826 100644
--- a/src/caosdb/logging.cpp
+++ b/src/caosdb/logging.cpp
@@ -59,6 +59,7 @@ auto LoggingConfiguration::GetSinks() const
 
 SinkConfiguration::SinkConfiguration(std::string name, int level)
   : LevelConfiguration(level), name(std::move(name)) {}
+
 [[nodiscard]] auto SinkConfiguration::GetName() const -> const std::string & {
   return this->name;
 }
@@ -77,6 +78,7 @@ auto SinkConfiguration::Configure(boost::log::settings &settings) const
 ConsoleSinkConfiguration::ConsoleSinkConfiguration(const std::string &name,
                                                    int level)
   : SinkConfiguration(name, level) {}
+
 [[nodiscard]] auto ConsoleSinkConfiguration::GetDestination() const
   -> const std::string & {
   CAOSDB_LOG_TRACE(logger_name)
@@ -93,12 +95,14 @@ auto ConsoleSinkConfiguration::Configure(boost::log::settings &settings) const
 
 FileSinkConfiguration::FileSinkConfiguration(const std::string &name, int level)
   : SinkConfiguration(name, level) {}
+
 [[nodiscard]] auto FileSinkConfiguration::GetDestination() const
   -> const std::string & {
   CAOSDB_LOG_TRACE(logger_name)
     << "Enter FileSinkConfiguration::GetDestination()";
   return this->destination;
 }
+
 auto FileSinkConfiguration::SetDirectory(const std::string &directory) -> void {
   this->directory = std::string(directory);
 }
@@ -114,11 +118,13 @@ auto FileSinkConfiguration::Configure(boost::log::settings &settings) const
 SyslogSinkConfiguration::SyslogSinkConfiguration(const std::string &name,
                                                  int level)
   : SinkConfiguration(name, level) {}
+
 [[nodiscard]] auto SyslogSinkConfiguration::GetDestination() const
   -> const std::string & {
   return this->destination;
 }
 
+// Called if no custom logging settings are specified.
 auto initialize_logging_defaults() -> int {
   // first: turn everything off
   boost::log::settings off_settings;
@@ -148,6 +154,7 @@ auto initialize_logging_defaults() -> int {
   return 0;
 }
 
+// Called if custom logging settings are specified.
 auto initialize_logging(const LoggingConfiguration &configuration) -> void {
   boost::log::settings new_settings;
 
-- 
GitLab