@@ -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

@@ -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())

 }

@@ -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"`

@@ -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.

@@ -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.

@@ -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