From 84740bd9aba4d62d6166b7f87233f058338632cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Henrik=20tom=20W=C3=B6rden?= <henrik@trineo.org>
Date: Tue, 17 Aug 2021 14:21:28 +0200
Subject: [PATCH] DOC: add docstrings
---
.../file_transmission/download_request_handler.h | 3 +++
include/caosdb/handler_interface.h | 15 ++++++++++++++-
include/caosdb/transaction.h | 2 ++
3 files changed, 19 insertions(+), 1 deletion(-)
diff --git a/include/caosdb/file_transmission/download_request_handler.h b/include/caosdb/file_transmission/download_request_handler.h
index c6ee1c3..cb2108a 100644
--- a/include/caosdb/file_transmission/download_request_handler.h
+++ b/include/caosdb/file_transmission/download_request_handler.h
@@ -68,6 +68,9 @@ using caosdb::entity::v1alpha1::FileTransmissionService;
using caosdb::transaction::HandlerInterface;
using caosdb::transaction::HandlerTag;
+/*
+ * Handler for the download request of a single file
+ */
class DownloadRequestHandler final : public HandlerInterface {
public:
DownloadRequestHandler(HandlerTag tag, FileTransmissionService::Stub *stub,
diff --git a/include/caosdb/handler_interface.h b/include/caosdb/handler_interface.h
index 4ba563a..ee38b38 100644
--- a/include/caosdb/handler_interface.h
+++ b/include/caosdb/handler_interface.h
@@ -56,7 +56,14 @@
namespace caosdb::transaction {
const static std::string logger_name = "caosdb::transaction";
-
+/*
+ * Baseclass for UnaryRpcHandler, DownloadRequestHandler and
+ * UploadRequestHandler
+ *
+ * It handles a request: Its status is contained in the transaction_status
+ * member variable and the functions Start, OnNext and Cancel need to be
+ * overwritten by child classes.
+ */
class HandlerInterface {
public:
HandlerInterface() : transaction_status(TransactionStatus::READY()) {}
@@ -65,6 +72,12 @@ public:
virtual void Start() = 0;
+ /*
+ * ok indicates whether the current request is in a good state or not. If
+ * ok is false, the request will be ended.
+ *
+ * returns false if the handler is done
+ */
virtual bool OnNext(bool ok) = 0;
virtual void Cancel() = 0;
diff --git a/include/caosdb/transaction.h b/include/caosdb/transaction.h
index 368eb2e..bda5bb3 100644
--- a/include/caosdb/transaction.h
+++ b/include/caosdb/transaction.h
@@ -432,6 +432,8 @@ public:
protected:
/**
* Await and process the current handler's results.
+ *
+ * This implies consecutive calls to the handler's OnNext function.
*/
auto ProcessCalls() -> TransactionStatus;
--
GitLab