Merge pull request #97 from ligato/jmedved

Editorial changes to README files.

datasync/grpcsync/doc.go

@@ -12,10 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package grpcsync implements (in ALPHA VERSION) the datasync API for the gRPC transport.
-// See the definition of the service in ../../syncbase/msg package). This
-// implementation is special (comparing to dbsync or msgsync) because it
-// does not use any intermediate persistence between the client and the
-// server. Therefore the client does remote  calls to each individual
-// server/agent instance (and needs to know its IP address & port).
+// Package grpcsync implements (in ALPHA VERSION) the gRPC transport client
+// and server that satisfy the datasync API. See the definition of the
+// service in ../../syncbase/msg package). This implementation is special
+// (comparing to dbsync or msgsync) because it does not use any intermediate
+// persistence between the client and the server. Therefore the client does
+// remote  calls to each individual server/agent instance (and needs to know
+// its IP address & port).
 package grpcsync

datasync/kvdbsync/doc.go

@@ -12,20 +12,23 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package kvdbsync implements the datasync API for data stores. The datasync
-// API contains the Data Broker & KeyValProtoWatcher APIs, which are basically facades
-// in front of different key-value or SQL stores.
+// Package kvdbsync implements the key-value data store client and server
+// that satisfythe datasync API. The datasync API contains the Data Broker
+// & KeyValProtoWatcher APIs, which are basically facades in front of
+// different key-value or SQL stores.
 //
 // A key-value store is used as a transport channel between a remote client
-// and the agent(server). It stores data/configuration for multiple agents(servers).
-// Therefore, a client only needs to know the address of the key-value store
-// but not the addresses of individual agents. The client can write
-// data/configuration independently of the agent's (server) lifecycle.
+// and the agent(server). It stores data/configuration for multiple agents
+// (servers). Therefore, a client only needs to know the address of the
+// key-value store but not the addresses of individual agents. The client
+// can write data/configuration independently of the agent's (server's)
+// lifecycle.
 //
-// The Data KeyValProtoWatcher is used during regular operation to efficiently propagate
-// data/configuration changes from the key & value store to the agents(servers).
-// Upon receiving data change events the watcher makes incremental updates to VPP.
-// When data resynchronization (RESYNC) is triggered then the Data Broker is used
-// to read all particular keys & values from the key-value store. Reading all
-// particular keys & values is more reliable but less efficient data synchronization.
+// The Data KeyValProtoWatcher is used during regular operation to efficiently
+// propagate data/configuration changes from the key & value store to the
+// agents (servers). Upon receiving a data change event, the watcher makes
+// an incremental update to its data. When data resynchronization (RESYNC) is
+// triggered, then the Data Broker is used to read all particular keys &
+// values from the key-value store. Reading all particular keys & values is
+// a more reliable but less efficient data synchronization method.
 package kvdbsync

datasync/restsync/doc.go

@@ -12,9 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package restsync implements (in ALPHA VERSION) the datasync API for the HTTP/REST transport.
-// This implementation is special (comparing to dbsync or bussync) because
-// it does not use any intermediate persistence between the client & server.
-// Therefore the client does remote calls to each individual server/agent
-// instance (and needs to know its IP address & port).
+// Package restsync implements (in ALPHA VERSION) the datasync API for the
+// HTTP/REST transport. This implementation is special (compared to dbsync
+// or bussync) because it does not use any intermediate persistence between
+// the client and the server. Therefore, the client does remote calls to each
+// individual server/agent instance (and needs to know its IP address & port).
 package restsync

datasync/resync/doc.go

@@ -12,6 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package resync contains implementation that notifies previously registered plugins
-// that resync procedure needs to start.
+// Package resync implements the mechanism to notify previously registered plugins
+// that the resync procedure needs to start.
 package resync

datasync/syncbase/doc.go

@@ -12,10 +12,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package syncbase contains reusable structures in multiple datasync transports.
-// See following reusable structures:
-// - KeyValProtoWatcher that maintains the registrations/subscriptions.
+// Package syncbase defines common structures used in multiple datasync
+// transports. The following reusable structures are defined:
+//
+// - KeyValProtoWatcher maintains watch registrations/subscriptions.
+//
 // - Registry of latest revisions of values per each key synchronized by datasync.
+//
 // - Default implementation of Events & Iterators interfaces defined in data_api.go.
-//   Events & Iterators in this package are reused (but not in all datasync transports).
+//
+// - Events & Iterators in this package are reused by some but all datasync transports.
 package syncbase

db/doc.go

@@ -12,6 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package db is the parent package for Data Broker client implementations
+// Package db is the parent package for the Data Broker client implementations
 // for various key-value and SQL data stores.
 package db

db/keyval/doc.go

@@ -12,7 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package keyval is an abstraction of a key-value data store, and it
-// defines the Data Broker client API (comprising the Broker and KeyValProtoWatcher
-// APIs) for accessing data in a key-value store.
+// Package keyval provides an abstraction of a key-value data store and a
+// definition of the Data Broker client API. The Data Broker client API
+// consists of the the Broker and KeyValProtoWatcher APIs for accessing
+// data in a key-value store.
 package keyval

db/sql/doc.go

@@ -12,7 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package sql is an abstraction of a data store that supports an SQL-like
-// query language, and it defines the Data Broker client API (comprising
-// the Broker and KeyValProtoWatcher APIs) for accessing data in a SQL data store.
+// Package sql provides an abstraction of a data store that supports
+// an SQL-like query language and a definition of the Data Broker client
+// API. The Data Broker client API consists of the the Broker and
+// KeyValProtoWatcher APIs for accessing data in an SQL data store.
 package sql