Merge pull request #1063 from peggyl/scheduler-strategy-godoc

Add more meaningful godoc comments for the scheduler/strategy package

scheduler/strategy/binpack.go

@@ -7,21 +7,21 @@ import (
 	"github.com/docker/swarm/scheduler/node"
 )
 
-// BinpackPlacementStrategy is exported
+// BinpackPlacementStrategy places a container onto the most packed node in the cluster.
 type BinpackPlacementStrategy struct {
 }
 
-// Initialize is exported
+// Initialize a BinpackPlacementStrategy.
 func (p *BinpackPlacementStrategy) Initialize() error {
 	return nil
 }
 
-// Name returns the name of the strategy
+// Name returns the name of the strategy.
 func (p *BinpackPlacementStrategy) Name() string {
 	return "binpack"
 }
 
-// PlaceContainer is exported
+// PlaceContainer places a container on the node with the most running containers.
 func (p *BinpackPlacementStrategy) PlaceContainer(config *cluster.ContainerConfig, nodes []*node.Node) (*node.Node, error) {
 	weightedNodes, err := weighNodes(config, nodes)
 	if err != nil {

scheduler/strategy/random.go

@@ -14,18 +14,18 @@ type RandomPlacementStrategy struct {
 	r *rand.Rand
 }
 
-// Initialize is exported
+// Initialize a RandomPlacementStrategy.
 func (p *RandomPlacementStrategy) Initialize() error {
 	p.r = rand.New(rand.NewSource(time.Now().UTC().UnixNano()))
 	return nil
 }
 
-// Name returns the name of the strategy
+// Name returns the name of the strategy.
 func (p *RandomPlacementStrategy) Name() string {
 	return "random"
 }
 
-// PlaceContainer is exported
+// PlaceContainer places the container on a random node in the cluster.
 func (p *RandomPlacementStrategy) PlaceContainer(config *cluster.ContainerConfig, nodes []*node.Node) (*node.Node, error) {
 	if size := len(nodes); size > 0 {
 		return nodes[p.r.Intn(size)], nil

scheduler/strategy/spread.go

@@ -7,21 +7,21 @@ import (
 	"github.com/docker/swarm/scheduler/node"
 )
 
-// SpreadPlacementStrategy is exported
+// SpreadPlacementStrategy places a container on the node with the fewest running containers.
 type SpreadPlacementStrategy struct {
 }
 
-// Initialize is exported
+// Initialize a SpreadPlacementStrategy.
 func (p *SpreadPlacementStrategy) Initialize() error {
 	return nil
 }
 
-// Name returns the name of the strategy
+// Name returns the name of the strategy.
 func (p *SpreadPlacementStrategy) Name() string {
 	return "spread"
 }
 
-// PlaceContainer is exported
+// PlaceContainer places a container on the node with the fewest running containers.
 func (p *SpreadPlacementStrategy) PlaceContainer(config *cluster.ContainerConfig, nodes []*node.Node) (*node.Node, error) {
 	weightedNodes, err := weighNodes(config, nodes)
 	if err != nil {

scheduler/strategy/strategy.go

@@ -8,21 +8,28 @@ import (
 	"github.com/docker/swarm/scheduler/node"
 )
 
-// PlacementStrategy is exported
+// PlacementStrategy is the interface for a container placement strategy.
 type PlacementStrategy interface {
+	// Name of the strategy
 	Name() string
-
+	// Initialize performs any initial configuration required by the strategy and returns
+	// an error if one is encountered.
+	// If no initial configuration is needed, this may be a no-op and return a nil error.
 	Initialize() error
 	// Given a container configuration and a set of nodes, select the target
-	// node where the container should be scheduled.
+	// node where the container should be scheduled. PlaceContainer returns
+	// an error if there is no available node on which to schedule the container.
 	PlaceContainer(config *cluster.ContainerConfig, nodes []*node.Node) (*node.Node, error)
 }
 
 var (
 	strategies []PlacementStrategy
-	// ErrNotSupported is exported
+	// ErrNotSupported is the error returned when a strategy name does not match
+	// any supported placement strategy.
 	ErrNotSupported = errors.New("strategy not supported")
-	// ErrNoResourcesAvailable is exported
+	// ErrNoResourcesAvailable is the error returned when there are no resources
+	// available to schedule a container. This can occur if there are no nodes in
+	// the cluster or if no node contains sufficient resources for the container.
 	ErrNoResourcesAvailable = errors.New("no resources available to schedule container")
 )
 
@@ -34,7 +41,7 @@ func init() {
 	}
 }
 
-// New is exported
+// New creates a new PlacementStrategy for the given strategy name.
 func New(name string) (PlacementStrategy, error) {
 	if name == "binpacking" { //TODO: remove this compat
 		name = "binpack"
@@ -51,7 +58,7 @@ func New(name string) (PlacementStrategy, error) {
 	return nil, ErrNotSupported
 }
 
-// List returns the names of all the available strategies
+// List returns the names of all the available strategies.
 func List() []string {
 	names := []string{}