From 61ea2abaf568bc9144e68f5985d478e8a1bb23fe Mon Sep 17 00:00:00 2001
From: Simon <simon@bitcartel.com>
Date: Wed, 7 Sep 2016 19:39:33 -0700
Subject: [PATCH] Update formatting and documentation.

---
 src/asyncrpcoperation.cpp |  8 ++++++--
 src/asyncrpcoperation.h   | 18 ++++++++++++------
 src/asyncrpcqueue.cpp     |  2 +-
 3 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/src/asyncrpcoperation.cpp b/src/asyncrpcoperation.cpp
index 7a66c451..9e4595c2 100644
--- a/src/asyncrpcoperation.cpp
+++ b/src/asyncrpcoperation.cpp
@@ -38,7 +38,8 @@ AsyncRPCOperation::AsyncRPCOperation() : error_code_(0), error_message_() {
     creation_time_ = (int64_t)time(NULL);
 }
 
-AsyncRPCOperation::AsyncRPCOperation(const AsyncRPCOperation& o) : id_(o.id_), creation_time_(o.creation_time_), state_(o.state_.load())
+AsyncRPCOperation::AsyncRPCOperation(const AsyncRPCOperation& o) :
+    id_(o.id_), creation_time_(o.creation_time_), state_(o.state_.load())
 {
 }
 
@@ -107,6 +108,7 @@ void AsyncRPCOperation::main() {
 
 /**
  * Return the error of the completed operation as a Value object.
+ * If there is no error, return null Value.
  */
 Value AsyncRPCOperation::getError() const {
     if (!isFailed()) {
@@ -121,6 +123,7 @@ Value AsyncRPCOperation::getError() const {
 
 /**
  * Return the result of the completed operation as a Value object.
+ * If the operation did not succeed, return null Value.
  */
 Value AsyncRPCOperation::getResult() const {
     if (!isSuccess()) {
@@ -135,6 +138,7 @@ Value AsyncRPCOperation::getResult() const {
  * Returns a status Value object.
  * If the operation has failed, it will include an error object.
  * If the operation has succeeded, it will include the result value.
+ * If the operation was cancelled, there will be no error object or result value.
  */
 Value AsyncRPCOperation::getStatus() const {
     OperationStatus status = this->getState();
@@ -142,7 +146,7 @@ Value AsyncRPCOperation::getStatus() const {
     obj.push_back(Pair("id", this->getId()));
     obj.push_back(Pair("status", OperationStatusMap[status]));
     obj.push_back(Pair("creation_time", this->creation_time_));
-    // creation, exec time, duration, exec end, etc.
+    // TODO: Issue #1354: There may be other useful metadata to return to the user.
     Value err = this->getError();
     if (!err.is_null()) {
         obj.push_back(Pair("error", err.get_obj()));
diff --git a/src/asyncrpcoperation.h b/src/asyncrpcoperation.h
index 99c3252d..9da76791 100644
--- a/src/asyncrpcoperation.h
+++ b/src/asyncrpcoperation.h
@@ -79,27 +79,33 @@ public:
     }
 
     bool isCancelled() const {
-        return OperationStatus::CANCELLED==getState();
+        return OperationStatus::CANCELLED == getState();
     }
 
     bool isExecuting() const {
-        return OperationStatus::EXECUTING==getState();
+        return OperationStatus::EXECUTING == getState();
     }
 
     bool isReady() const {
-        return OperationStatus::READY==getState();
+        return OperationStatus::READY == getState();
     }
 
     bool isFailed() const {
-        return OperationStatus::FAILED==getState();
+        return OperationStatus::FAILED == getState();
     }
     
     bool isSuccess() const {
-        return OperationStatus::SUCCESS==getState();
+        return OperationStatus::SUCCESS == getState();
     }
 
 protected:
-
+    // The state_ is atomic because only it can be mutated externally.
+    // For example, the user initiates a shut down of the application, which closes
+    // the AsyncRPCQueue, which in turn invokes cancel() on all operations.
+    // The member variables below are protected rather than private in order to
+    // allow subclasses of AsyncRPCOperation the ability to access and update
+    // internal state.  Currently, all operations are executed in a single-thread
+    // by a single worker.
     Value result_;
     int error_code_;
     std::string error_message_;
diff --git a/src/asyncrpcqueue.cpp b/src/asyncrpcqueue.cpp
index 2febe0ce..3dd13df5 100644
--- a/src/asyncrpcqueue.cpp
+++ b/src/asyncrpcqueue.cpp
@@ -37,7 +37,7 @@ void AsyncRPCQueue::run(size_t workerId) {
             }
 
             // Exit if the queue is empty and we are finishing up
-            if ( isFinishing() && operation_id_queue_.empty() ) {
+            if (isFinishing() && operation_id_queue_.empty()) {
                 break;
             }