add swarm type comments and fix nits

Signed-off-by: allencloud <allen.sun@daocloud.io>

api/types/client.go

@@ -84,7 +84,7 @@ type CopyToContainerOptions struct {
 	AllowOverwriteDirWithFile bool
 }
 
-// EventsOptions hold parameters to filter events with.
+// EventsOptions holds parameters to filter events with.
 type EventsOptions struct {
 	Since   string
 	Until   string

api/types/container/hostconfig_unix.go

@@ -9,7 +9,7 @@ func (i Isolation) IsValid() bool {
 	return i.IsDefault()
 }
 
-// IsPrivate indicates whether container uses it's private network stack.
+// IsPrivate indicates whether container uses its private network stack.
 func (n NetworkMode) IsPrivate() bool {
 	return !(n.IsHost() || n.IsContainer())
 }

api/types/swarm/common.go

@@ -2,12 +2,12 @@ package swarm
 
 import "time"
 
-// Version represent the internal object version.
+// Version represents the internal object version.
 type Version struct {
 	Index uint64 `json:",omitempty"`
 }
 
-// Meta is  base object inherited by most of the other once.
+// Meta is a base object inherited by most of the other once.
 type Meta struct {
 	Version   Version   `json:",omitempty"`
 	CreatedAt time.Time `json:",omitempty"`

api/types/swarm/node.go

@@ -4,11 +4,17 @@ package swarm
 type Node struct {
 	ID string
 	Meta
-
-	Spec          NodeSpec        `json:",omitempty"`
-	Description   NodeDescription `json:",omitempty"`
-	Status        NodeStatus      `json:",omitempty"`
-	ManagerStatus *ManagerStatus  `json:",omitempty"`
+	// Spec defines the desired state of the node as specified by the user.
+	// The system will honor this and will *never* modify it.
+	Spec NodeSpec `json:",omitempty"`
+	// Description encapsulates the properties of the Node as reported by the
+	// agent.
+	Description NodeDescription `json:",omitempty"`
+	// Status provides the current status of the node, as seen by the manager.
+	Status NodeStatus `json:",omitempty"`
+	// ManagerStatus provides the current status of the node's manager
+	// component, if the node is a manager.
+	ManagerStatus *ManagerStatus `json:",omitempty"`
 }
 
 // NodeSpec represents the spec of a node.

api/types/swarm/swarm.go

@@ -18,7 +18,9 @@ type Swarm struct {
 
 // JoinTokens contains the tokens workers and managers need to join the swarm.
 type JoinTokens struct {
-	Worker  string
+	// Worker is the join token workers may use to join the swarm.
+	Worker string
+	// Manager is the join token managers may use to join the swarm.
 	Manager string
 }
 
@@ -35,6 +37,8 @@ type Spec struct {
 
 // OrchestrationConfig represents orchestration configuration.
 type OrchestrationConfig struct {
+	// TaskHistoryRetentionLimit is the number of historic tasks to keep per instance or
+	// node. If negative, never remove completed or failed tasks.
 	TaskHistoryRetentionLimit int64 `json:",omitempty"`
 }
 
@@ -51,8 +55,15 @@ type TaskDefaults struct {
 
 // RaftConfig represents raft configuration.
 type RaftConfig struct {
-	SnapshotInterval           uint64 `json:",omitempty"`
-	KeepOldSnapshots           uint64 `json:",omitempty"`
+	// SnapshotInterval is the number of log entries between snapshots.
+	SnapshotInterval uint64 `json:",omitempty"`
+
+	// KeepOldSnapshots is the number of snapshots to keep beyond the
+	// current snapshot.
+	KeepOldSnapshots uint64 `json:",omitempty"`
+
+	// LogEntriesForSlowFollowers is the number of log entries to keep
+	// around to sync up slow followers after a snapshot is created.
 	LogEntriesForSlowFollowers uint64 `json:",omitempty"`
 
 	// ElectionTick is the number of ticks that a follower will wait for a message
@@ -74,13 +85,19 @@ type RaftConfig struct {
 
 // DispatcherConfig represents dispatcher configuration.
 type DispatcherConfig struct {
+	// HeartbeatPeriod defines how often agent should send heartbeats to
+	// dispatcher.
 	HeartbeatPeriod time.Duration `json:",omitempty"`
 }
 
 // CAConfig represents CA configuration.
 type CAConfig struct {
+	// NodeCertExpiry is the duration certificates should be issued for
 	NodeCertExpiry time.Duration `json:",omitempty"`
-	ExternalCAs    []*ExternalCA `json:",omitempty"`
+
+	// ExternalCAs is a list of CAs to which a manager node will make
+	// certificate signing requests for node certificates.
+	ExternalCAs []*ExternalCA `json:",omitempty"`
 }
 
 // ExternalCAProtocol represents type of external CA.
@@ -91,9 +108,15 @@ const ExternalCAProtocolCFSSL ExternalCAProtocol = "cfssl"
 
 // ExternalCA defines external CA to be used by the cluster.
 type ExternalCA struct {
+	// Protocol is the protocol used by this external CA.
 	Protocol ExternalCAProtocol
-	URL      string
-	Options  map[string]string `json:",omitempty"`
+
+	// URL is the URL where the external CA can be reached.
+	URL string
+
+	// Options is a set of additional key/value pairs whose interpretation
+	// depends on the specified CA type.
+	Options map[string]string `json:",omitempty"`
 }
 
 // InitRequest is the request used to init a swarm.

api/types/types.go

@@ -183,7 +183,7 @@ type ContainerPathStat struct {
 	LinkTarget string      `json:"linkTarget"`
 }
 
-// ContainerStats contains resonse of Remote API:
+// ContainerStats contains response of Remote API:
 // GET "/stats"
 type ContainerStats struct {
 	Body   io.ReadCloser `json:"body"`
@@ -446,7 +446,7 @@ type VolumesListResponse struct {
 	Warnings []string  // Warnings is a list of warnings that occurred when getting the list from the volume drivers
 }
 
-// VolumeCreateRequest contains the response for the remote API:
+// VolumeCreateRequest contains the request for the remote API:
 // POST "/volumes/create"
 type VolumeCreateRequest struct {
 	Name       string            // Name is the requested name of the volume