From 9ead41d87952a0e64c7b4bc7e6cd888766e7c6ce Mon Sep 17 00:00:00 2001
From: Jerin Philip <jphilip@ed.ac.uk>
Date: Fri, 26 Feb 2021 10:33:07 +0000
Subject: [PATCH] Adds documentation, makes enqueue() private

---
 src/translator/service.h      |  9 ++++++++-
 src/translator/service_base.h | 25 +++++++++++++++++++------
 2 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/src/translator/service.h b/src/translator/service.h
index b2fb617..9a57996 100644
--- a/src/translator/service.h
+++ b/src/translator/service.h
@@ -32,11 +32,18 @@ class Service : public ServiceBase {
 
 public:
   explicit Service(Ptr<Options> options);
-  void enqueue() override;
+  // Implements enqueue and top through blocking methods.
   void stop() override;
   ~Service();
 
 private:
+  void enqueue() override;
+
+  // In addition to the common members (text_processor, requestId, vocabs_,
+  // batcher) extends with a producer-consumer queue, vector of translator
+  // instances owned by service each listening to the pcqueue in separate
+  // threads.
+
   size_t numWorkers_;      // ORDER DEPENDENCY
   PCQueue<Batch> pcqueue_; // ORDER DEPENDENCY
   std::vector<std::thread> workers_;
diff --git a/src/translator/service_base.h b/src/translator/service_base.h
index 3482ec8..25cc003 100644
--- a/src/translator/service_base.h
+++ b/src/translator/service_base.h
@@ -11,21 +11,31 @@
 
 namespace marian {
 namespace bergamot {
+// This file describes the base class ServiceBase, and a non-threaded subclass
+// implementing translation functionality called NonThreadedService.
 
 class ServiceBase {
 public:
   explicit ServiceBase(Ptr<Options> options);
-  std::future<Response> translateWithCopy(std::string input) {
-    return translate(std::move(input));
-  };
 
+  // Transfers ownership of input string to Service, returns a future containing
+  // an object which provides access to translations, other features like
+  // sentencemappings and (tentatively) alignments.
   std::future<Response> translate(std::string &&input);
+
+  // Convenience accessor methods to extract these vocabulary outside service.
+  // e.g: For use in decoding histories for marian-decoder replacement.
   Ptr<Vocab const> sourceVocab() const { return vocabs_.front(); }
   Ptr<Vocab const> targetVocab() const { return vocabs_.back(); }
-  virtual void enqueue() = 0;
+
+  // Wraps up any thread related destruction code.
   virtual void stop() = 0;
 
 protected:
+  // Enqueue queues a request for translation, this can be synchronous, blocking
+  // or asynchronous and queued in the background.
+  virtual void enqueue() = 0;
+
   size_t requestId_;
   std::vector<Ptr<Vocab const>> vocabs_; // ORDER DEPENDENCY
   TextProcessor text_processor_;         // ORDER DEPENDENCY
@@ -35,14 +45,17 @@ protected:
 class NonThreadedService : public ServiceBase {
 public:
   explicit NonThreadedService(Ptr<Options> options);
-  void enqueue() override;
   void stop() override{};
 
 private:
+  // NonThreaded service overrides unimplemented functions in base-class using
+  // blocking mechanisms.
+  void enqueue() override;
+  // There's a single translator, launched as part of the main process.
   BatchTranslator translator_;
 };
 
-// Internal function nobody used, only within service.
+// Used across Services
 inline std::vector<Ptr<const Vocab>> loadVocabularies(Ptr<Options> options) {
   // @TODO: parallelize vocab loading for faster startup
   auto vfiles = options->get<std::vector<std::string>>("vocabs");