DOC: docstrings for MultiResultSet and TransactionType

include/caosdb/transaction.h

@@ -124,6 +124,9 @@ class Transaction;
 
 static const std::string logger_name = "caosdb::transaction";
 
+/**
+ * Abstract base class for the results of a Transaction.
+ */
 class ResultSet {
 public:
   virtual ~ResultSet() = default;
@@ -131,6 +134,12 @@ public:
   [[nodiscard]] virtual auto At(const int index) const -> const Entity & = 0;
 };
 
+/**
+ * Container with results of a transaction.
+ *
+ * In contrast to UniqueResult, this one can also hold multiple entities or zero
+ * entities.
+ */
 class MultiResultSet : public ResultSet {
 public:
   ~MultiResultSet() = default;
@@ -145,6 +154,12 @@ public:
   std::vector<std::unique_ptr<Entity>> entities;
 };
 
+/**
+ * Container with the single result of a transaction.
+ *
+ * In contrast to MultiResultSet, this one guarantees to hold exactly one
+ * entity.
+ */
 class UniqueResult : public ResultSet {
 public:
   ~UniqueResult() = default;
@@ -171,14 +186,21 @@ private:
  */
 class Transaction {
 public:
+  /**
+   * The transaction type restricts the kind of sub-transaction which may be
+   * added to a transaction (insertion, update, deletion, retrieval).
+   *
+   * @note MIXED_READ_AND_WRITE and MIXED_WRITE transaction are not supported
+   * yet.
+   */
   enum TransactionType {
-    NONE,
-    READ_ONLY,
-    INSERT,
-    UPDATE,
-    DELETE,
-    MIXED_WRITE,
-    MIXED_READ_AND_WRITE
+    NONE,                /// Unspecified or not specified yet.
+    READ_ONLY,           /// Only retrievals (by id, by query)
+    INSERT,              /// Only insertions
+    UPDATE,              /// Only updates
+    DELETE,              /// Only deletions
+    MIXED_WRITE,         /// Only insertions, deletions, updates
+    MIXED_READ_AND_WRITE /// all kind of transaction.
   };
   Transaction(std::shared_ptr<EntityTransactionService::Stub> service_stub);