add comments

Author: longquanzheng

Diff for: common/persistence/nosql/nosqlplugin/interfaces.go

@@ -99,7 +99,7 @@ type (
 	 * Recommendation: use two tables(queue_message,and queue_metadata) to implement this interface
 	 * Significant columns:
 	 * queue_message partition key: (queueType), range key: (messageID)
-	 * queue_metadata partition key: (queueType), range key: N/A
+	 * queue_metadata partition key: (queueType), range key: N/A, query condition column(version)
 	 */
 	messageQueueCRUD interface {
 		//Insert message into queue, return error if failed or already exists
@@ -133,15 +133,17 @@ type (
 	/***
 	* domainCRUD is for domain + domain metadata storage system
 	*
-	* Recommendation: Use one table to implement
+	* Recommendation: Use two tables(domain, domain_metadata) to implement if conditional updates on two tables is supported
 	* Significant columns:
 	* domain: partition key( a constant value), range key(domainName), local secondary index(domainID)
+	* domain_metadata: partition key( a constant value), range key(a constant value), query condition column(notificationVersion)
 	*
 	* Note 1: About Cassandra's implementation: Because of historical reasons, Cassandra uses two table,
 	* domains and domains_by_name_v2. Therefore, Cassandra implementation lost the atomicity causing some edge cases,
 	* and the implementation is more complicated than it should be.
 	*
-	* Note 2: About the special record as "domain metadata". Right now it is an integer number as notification version.
+	* Note 2: Cassandra doesn't support conditional updates on multiple tables. Hence the domain_metadata table is implemented
+	* as a special record as "domain metadata". It is an integer number as notification version.
 	* The main purpose of it is to notify clusters that there is some changes in domains, so domain cache needs to refresh.
 	* It always increase by one, whenever a domain is updated or inserted.
 	* Updating this failover metadata with domain insert/update needs to be atomic.
@@ -166,16 +168,20 @@ type (
 		SelectDomainMetadata(ctx context.Context) (int64, error)
 	}
 
-	// shardCRUD is for shard storage of workflow execution.
-	//
-	// Recommendation: use one table if database support batch conditional update on multiple tables, otherwise combine with workflowCRUD (likeCassandra)
-	// shard: partition key(shardID), range key(N/A)
-	//
-	// Note 1: shard will be required to run conditional update with workflowCRUD. So in some nosql database like Cassandra,
-	// shardCRUD and workflowCRUD must be implemented within the same table. Because Cassandra only allows LightWeight transaction
-	// executed within a single table.
-	// Note 2: unlike Cassandra, most NoSQL databases don't return the previous rows when conditional write fails. In this case,
-	// an extra read query is needed to get the previous row.
+	/**
+		* shardCRUD is for shard storage of workflow execution.
+
+		* Recommendation: use one table if database support batch conditional update on multiple tables, otherwise combine with workflowCRUD (likeCassandra)
+		*
+		* Significant columns:
+		* domain: partition key(shardID), range key(N/A), local secondary index(domainID), query condition column(rangeID)
+	 	*
+		* Note 1: shard will be required to run conditional update with workflowCRUD. So in some nosql database like Cassandra,
+		* shardCRUD and workflowCRUD must be implemented within the same table. Because Cassandra only allows LightWeight transaction
+		* executed within a single table.
+		* Note 2: unlike Cassandra, most NoSQL databases don't return the previous rows when conditional write fails. In this case,
+		* an extra read query is needed to get the previous row.
+	*/
 	shardCRUD interface {
 		// InsertShard creates a new shard.
 		// Return error is there is any thing wrong