Merge pull request #532 from peggyl/500-api-pkg-godoc

Improve godocs for exported values in api pkg

api/api.go

@@ -22,7 +22,7 @@ import (
 	"github.com/samalba/dockerclient"
 )
 
-// APIVERSION is exported
+// The Client API version
 const APIVERSION = "1.16"
 
 type context struct {

api/events.go

@@ -15,7 +15,8 @@ type eventsHandler struct {
 	cs map[string]chan struct{}
 }
 
-// NewEventsHandler is exported
+// NewEventsHandler creates a new eventsHandler for a cluster.
+// The new eventsHandler is initialized with no writers or channels.
 func NewEventsHandler() *eventsHandler {
 	return &eventsHandler{
 		ws: make(map[string]io.Writer),
@@ -23,6 +24,7 @@ func NewEventsHandler() *eventsHandler {
 	}
 }
 
+// Add adds the writer and a new channel for the remote address.
 func (eh *eventsHandler) Add(remoteAddr string, w io.Writer) {
 	eh.Lock()
 	eh.ws[remoteAddr] = w
@@ -30,10 +32,13 @@ func (eh *eventsHandler) Add(remoteAddr string, w io.Writer) {
 	eh.Unlock()
 }
 
+// Wait waits on a signal from the remote address.
 func (eh *eventsHandler) Wait(remoteAddr string) {
 	<-eh.cs[remoteAddr]
 }
 
+// Handle writes information about a cluster event to each remote address in the cluster that has been added to the events handler.
+// After a successful write to a remote address, the associated channel is closed and the address is removed from the events handler.
 func (eh *eventsHandler) Handle(e *cluster.Event) error {
 	eh.RLock()
 
@@ -61,6 +66,7 @@ func (eh *eventsHandler) Handle(e *cluster.Event) error {
 	return nil
 }
 
+// Size returns the number of remote addresses that the events handler currently contains.
 func (eh *eventsHandler) Size() int {
 	eh.RLock()
 	defer eh.RUnlock()

api/flusher.go

@@ -8,13 +8,14 @@ import (
 	"github.com/docker/docker/pkg/ioutils"
 )
 
-// WriteFlusher is exported
+// A WriteFlusher provides synchronized write access to the writer's underlying data stream and ensures that each write is flushed immediately.
 type WriteFlusher struct {
 	sync.Mutex
 	w       io.Writer
 	flusher http.Flusher
 }
 
+// Write writes the bytes to a stream and flushes the stream.
 func (wf *WriteFlusher) Write(b []byte) (n int, err error) {
 	wf.Lock()
 	defer wf.Unlock()
@@ -23,14 +24,14 @@ func (wf *WriteFlusher) Write(b []byte) (n int, err error) {
 	return n, err
 }
 
-// Flush the stream immediately.
+// Flush flushes the stream immediately.
 func (wf *WriteFlusher) Flush() {
 	wf.Lock()
 	defer wf.Unlock()
 	wf.flusher.Flush()
 }
 
-// NewWriteFlusher is exported
+// NewWriteFlusher creates a new WriteFlusher for the writer.
 func NewWriteFlusher(w io.Writer) *WriteFlusher {
 	var flusher http.Flusher
 	if f, ok := w.(http.Flusher); ok {

api/server.go

@@ -11,7 +11,7 @@ import (
 	"github.com/docker/swarm/cluster"
 )
 
-// DefaultDockerPort is exported
+// The default port to listen on for incoming connections
 const DefaultDockerPort = ":2375"
 
 func newListener(proto, addr string, tlsConfig *tls.Config) (net.Listener, error) {
@@ -29,7 +29,12 @@ func newListener(proto, addr string, tlsConfig *tls.Config) (net.Listener, error
 	return l, nil
 }
 
-// ListenAndServe is exported
+// ListenAndServe starts an HTTP server on each host to listen on its
+// TCP or Unix network address and calls Serve on each host's server
+// to handle requests on incoming connections.
+//
+// The expected format for a host string is [protocol://]address. The protocol
+// must be either "tcp" or "unix", with "tcp" used by default if not specified.
 func ListenAndServe(c cluster.Cluster, hosts []string, enableCors bool, tlsConfig *tls.Config, eventsHandler *eventsHandler) error {
 	context := &context{
 		cluster:       c,

api/sorter.go

@@ -4,17 +4,22 @@ import (
 	"github.com/samalba/dockerclient"
 )
 
-// ContainerSorter is exported
+// ContainerSorter implements the Sort interface to sort Docker containers.
+// It is not guaranteed to be a stable sort.
 type ContainerSorter []*dockerclient.Container
 
+// Len returns the number of containers to be sorted.
 func (s ContainerSorter) Len() int {
 	return len(s)
 }
 
+// Swap exchanges the container elements with indices i and j.
 func (s ContainerSorter) Swap(i, j int) {
 	s[i], s[j] = s[j], s[i]
 }
 
+// Less reports whether the container with index i should sort before the container with index j.
+// Containers are sorted chronologically by when they were created.
 func (s ContainerSorter) Less(i, j int) bool {
 	return s[i].Created < s[j].Created
 }