style(deisctl): add code doc strings

Author: mboersma

deisctl/client/client.go

@@ -8,6 +8,7 @@ import (
 	"github.com/deis/deis/deisctl/cmd"
 )
 
+// DeisCtlClient manages Deis components, configuration, and related tasks.
 type DeisCtlClient interface {
 	Config() error
 	Install(targets []string) error
@@ -23,10 +24,13 @@ type DeisCtlClient interface {
 	Update() error
 }
 
+// Client uses a backend to implement the DeisCtlClient interface.
 type Client struct {
 	Backend backend.Backend
 }
 
+// NewClient returns a Client using the requested backend.
+// The only backend currently supported is "fleet".
 func NewClient(requestedBackend string) (*Client, error) {
 	var backend backend.Backend
 
@@ -47,50 +51,66 @@ func NewClient(requestedBackend string) (*Client, error) {
 	return &Client{Backend: backend}, nil
 }
 
+// Config gets or sets a configuration value from the cluster.
+//
+// A configuration value is stored and retrieved from a key/value store (in this case, etcd)
+// at /deis/<component>/<config>. Configuration values are typically used for component-level
+// configuration, such as enabling TLS for the routers.
 func (c *Client) Config() error {
 	return cmd.Config()
 }
 
+// Install loads components' definitions from local unit files.
 func (c *Client) Install(targets []string) error {
 	return cmd.Install(c.Backend, targets)
 }
 
+// Journal prints log output for the specified components.
 func (c *Client) Journal(targets []string) error {
 	return cmd.Journal(c.Backend, targets)
 }
 
+// List prints a summary of installed components.
 func (c *Client) List() error {
 	return cmd.ListUnits(c.Backend)
 }
 
+// RefreshUnits overwrites local unit files with those requested.
 func (c *Client) RefreshUnits() error {
 	return cmd.RefreshUnits()
 }
 
+// Restart stops and then starts components.
 func (c *Client) Restart(targets []string) error {
 	return cmd.Restart(c.Backend, targets)
 }
 
+// Scale grows or shrinks the number of running components.
 func (c *Client) Scale(targets []string) error {
 	return cmd.Scale(c.Backend, targets)
 }
 
+// Start activates the specified components.
 func (c *Client) Start(targets []string) error {
 	return cmd.Start(c.Backend, targets)
 }
 
+// Status prints the current state of components.
 func (c *Client) Status(targets []string) error {
 	return cmd.Status(c.Backend, targets)
 }
 
+// Stop deactivates the specified components.
 func (c *Client) Stop(targets []string) error {
 	return cmd.Stop(c.Backend, targets)
 }
 
+// Uninstall unloads components' definitions.
 func (c *Client) Uninstall(targets []string) error {
 	return cmd.Uninstall(c.Backend, targets)
 }
 
+// Update changes the platform version on a cluster host.
 func (c *Client) Update() error {
 	return cmd.Update()
 }

deisctl/cmd/cmd.go

@@ -24,19 +24,23 @@ import (
 )
 
 const (
+	// PlatformInstallCommand is shorthand for "all the Deis components."
 	PlatformInstallCommand string = "platform"
 )
 
+// ListUnits prints a list of installed units.
 func ListUnits(b backend.Backend) error {
-	err := b.ListUnits()
-	return err
+	return b.ListUnits()
 }
 
+// ListUnitFiles prints the contents of all defined unit files.
 func ListUnitFiles(b backend.Backend) error {
 	err := b.ListUnitFiles()
 	return err
 }
 
+// Scale grows or shrinks the number of running components.
+// Currently "router" is the only type that can be scaled.
 func Scale(b backend.Backend, targets []string) error {
 	outchan := make(chan string)
 	errchan := make(chan error)
@@ -60,6 +64,7 @@ func Scale(b backend.Backend, targets []string) error {
 	return nil
 }
 
+// Start activates the specified components.
 func Start(b backend.Backend, targets []string) error {
 
 	if len(targets) == 1 && targets[0] == PlatformInstallCommand {
@@ -94,6 +99,7 @@ deisctl config platform set sshPrivateKey=<path-to-key>
 	return nil
 }
 
+// StartPlatform activates all components.
 func StartPlatform(b backend.Backend) error {
 
 	outchan := make(chan string)
@@ -165,6 +171,7 @@ func startDefaultServices(b backend.Backend, wg *sync.WaitGroup, outchan chan st
 	wg.Wait()
 }
 
+// Stop deactivates the specified components.
 func Stop(b backend.Backend, targets []string) error {
 
 	if len(targets) == 1 && targets[0] == PlatformInstallCommand {
@@ -184,6 +191,7 @@ func Stop(b backend.Backend, targets []string) error {
 	return nil
 }
 
+// StopPlatform deactivates all components.
 func StopPlatform(b backend.Backend) error {
 
 	outchan := make(chan string)
@@ -234,13 +242,15 @@ func stopDefaultServices(b backend.Backend, wg *sync.WaitGroup, outchan chan str
 	wg.Wait()
 }
 
+// Restart stops and then starts components.
 func Restart(b backend.Backend, targets []string) error {
 	if err := Stop(b, targets); err != nil {
 		return err
 	}
 	return Start(b, targets)
 }
 
+// Status prints the current state of components.
 func Status(b backend.Backend, targets []string) error {
 	for _, target := range targets {
 		if err := b.Status(target); err != nil {
@@ -250,6 +260,7 @@ func Status(b backend.Backend, targets []string) error {
 	return nil
 }
 
+// Journal prints log output for the specified components.
 func Journal(b backend.Backend, targets []string) error {
 	for _, target := range targets {
 		if err := b.Journal(target); err != nil {
@@ -259,6 +270,8 @@ func Journal(b backend.Backend, targets []string) error {
 	return nil
 }
 
+// Install loads components' definitions from local unit files.
+// After Install, the components will be available to Start.
 func Install(b backend.Backend, targets []string) error {
 
 	// if target is platform, install all services
@@ -280,6 +293,8 @@ func Install(b backend.Backend, targets []string) error {
 	return nil
 }
 
+// InstallPlatform loads all components' definitions from local unit files.
+// After InstallPlatform, all components will be available for StartPlatform.
 func InstallPlatform(b backend.Backend) error {
 
 	if err := checkRequiredKeys(); err != nil {
@@ -328,6 +343,8 @@ func installDefaultServices(b backend.Backend, wg *sync.WaitGroup, outchan chan
 	wg.Wait()
 }
 
+// Uninstall unloads components' definitions.
+// After Uninstall, the component will be unavailable until Install is called.
 func Uninstall(b backend.Backend, targets []string) error {
 
 	// if target is platform, uninstall all services
@@ -349,6 +366,8 @@ func Uninstall(b backend.Backend, targets []string) error {
 	return nil
 }
 
+// UninstallPlatform unloads all components' definitions.
+// After UninstallPlatform, all components will be unavailable.
 func UninstallPlatform(b backend.Backend) error {
 
 	outchan := make(chan string)
@@ -432,13 +451,15 @@ func splitScaleTarget(target string) (c string, num int, err error) {
 	return
 }
 
+// Config gets or sets a configuration value in the cluster.
 func Config() error {
 	if err := config.Config(); err != nil {
 		return err
 	}
 	return nil
 }
 
+// Update changes the platform version on a cluster host.
 func Update() error {
 	if err := utils.Execute(constant.HooksDir + "pre-update"); err != nil {
 		fmt.Println("pre-updatehook failed")
@@ -455,6 +476,9 @@ func Update() error {
 	return nil
 }
 
+// RefreshUnits overwrites local unit files with those requested.
+// Downloading from the Deis project GitHub URL by tag or SHA is the only mechanism
+// currently supported.
 func RefreshUnits() error {
 	usage := `Refreshes local unit files from the master repository.
 

deisctl/constant/constants.go

@@ -3,11 +3,24 @@ package constant
 import "time"
 
 const (
-	UnitsDir        = "/var/lib/deis/units/"
-	HooksDir        = "/var/lib/deis/hooks/"
-	Version         = "/etc/deis-version"
-	MachineID       = "/etc/machine-id"
-	UpdatekeyDir    = "/deis/update/"
+	// UnitsDir is the default directory for unit files.
+	UnitsDir = "/var/lib/deis/units/"
+
+	// HooksDir is the default directory for hook scripts.
+	HooksDir = "/var/lib/deis/hooks/"
+
+	// Version is the location of the deis-version text file.
+	Version = "/etc/deis-version"
+
+	// MachineID is the location of the machine-id file.
+	MachineID = "/etc/machine-id"
+
+	// UpdatekeyDir is the etcd directory for update data.
+	UpdatekeyDir = "/deis/update/"
+
+	// InitialInterval specifies how long to wait at first between update loops.
 	InitialInterval = time.Second * 10
-	MaxInterval     = time.Minute * 7
+
+	// MaxInterval is the longest time allowed to wait between loops.
+	MaxInterval = time.Minute * 7
 )

deisctl/update/client.go

@@ -21,6 +21,7 @@ import (
 	"github.com/deis/deis/deisctl/utils"
 )
 
+// Client handles locking, update server interactions, and node updates.
 type Client struct {
 	ID             string
 	SessionID      string
@@ -33,6 +34,7 @@ type Client struct {
 	lock           *lock.Lock
 }
 
+// Logf prints a log message prefixed by Client.ID.
 func (c *Client) Logf(format string, args ...interface{}) {
 	format = c.ID + ": " + format
 	fmt.Printf(format, args...)
@@ -47,6 +49,7 @@ func (c *Client) getCodebaseURL(uc *omaha.UpdateCheck) string {
 	return uc.Urls.Urls[0].CodeBase + uc.Manifest.Packages.Packages[0].Name
 }
 
+// RequestLock asks for a new etcd Lock.
 func (c *Client) RequestLock() {
 	elc, err := lock.NewEtcdLockClient(nil)
 	if err != nil {
@@ -60,7 +63,10 @@ func (c *Client) RequestLock() {
 	c.lock = lock.New(mID, elc)
 }
 
-func (c *Client) OmahaRequest(otype, result string, updateCheck, isPing bool) *omaha.Request {
+// OmahaRequest returns an update server Request of the specified type.
+func (c *Client) OmahaRequest(
+	otype, result string, updateCheck, isPing bool) *omaha.Request {
+
 	req := omaha.NewRequest("lsb", "CoreOS", "", "")
 	app := req.AddApp(c.AppID, c.Version)
 	app.MachineID = c.ID
@@ -92,6 +98,7 @@ func (c *Client) OmahaRequest(otype, result string, updateCheck, isPing bool) *o
 	return req
 }
 
+// MakeRequest queries the omaha update server and returns its Response.
 func (c *Client) MakeRequest(otype, result string, updateCheck, isPing bool) (*omaha.Response, error) {
 	client := &http.Client{}
 	req := c.OmahaRequest(otype, result, updateCheck, isPing)
@@ -122,7 +129,7 @@ func (c *Client) MakeRequest(otype, result string, updateCheck, isPing bool) (*o
 	return oresp, nil
 }
 
-// Loop between n and m seconds
+// Loop repeatedly makes a request, pausing a random amount between n and m seconds.
 func (c *Client) Loop(n, m int) {
 	interval := constant.InitialInterval
 	for {
@@ -178,6 +185,7 @@ func (c *Client) Loop(n, m int) {
 	}
 }
 
+// SetVersion specifies the particular platform version for update.
 func (c *Client) SetVersion(resp *omaha.Response) {
 	// A field can potentially be nil.
 	defer func() {
@@ -218,6 +226,7 @@ func (c *Client) SetVersion(resp *omaha.Response) {
 	c.SessionID = uuid.New()
 }
 
+// Update changes services on a node to match the requested version.
 func (c *Client) Update() (err error) {
 	deis, _ := fleet.NewClient()
 	localServices := deis.GetLocaljobs()

deisctl/utils/utils.go

@@ -37,6 +37,8 @@ func getetcdClient() *etcd.Client {
 	return c
 }
 
+// GetKey returns the value of an etcd key, or of an environment variable if etcd didn't have
+// a value.
 func GetKey(dir, key, perm string) string {
 	c := getetcdClient()
 	result, err := c.Get(dir+key, false, false)
@@ -55,7 +57,7 @@ func PullImage(args string) error {
 	return nil
 }
 
-// GetClientID returns the CoreOS Machine ID or an unknown UUID string
+// GetClientID returns the CoreOS Machine ID, or an unknown UUID string.
 func GetClientID() string {
 	machineID := GetMachineID("/")
 	if machineID == "" {
@@ -64,6 +66,7 @@ func GetClientID() string {
 	return machineID
 }
 
+// GetMachineID returns the CoreOS Machine ID.
 func GetMachineID(root string) string {
 	fullPath := filepath.Join(root, constant.MachineID)
 	id, err := ioutil.ReadFile(fullPath)
@@ -73,6 +76,7 @@ func GetMachineID(root string) string {
 	return strings.TrimSpace(string(id))
 }
 
+// GetVersion returns the package version from a text file resource.
 func GetVersion() string {
 	id, err := ioutil.ReadFile(constant.Version)
 	if err != nil {
@@ -106,6 +110,7 @@ func CreateFile(path string) error {
 	return nil
 }
 
+// Extract expands a .tar archive file into the specified directory.
 func Extract(file, dir string) (err error) {
 	var wd, _ = os.Getwd()
 	_ = os.Chdir(dir)
@@ -144,6 +149,7 @@ func GetHostIPAddress() string {
 	return IP
 }
 
+// PutVersion updates the package version to a local text file resource.
 func PutVersion(version string) error {
 	err := ioutil.WriteFile(constant.Version, []byte(version), 0644)
 	if err != nil {
@@ -217,6 +223,7 @@ func RunCommandWithStdoutStderr(cmd *exec.Cmd) (bytes.Buffer, bytes.Buffer, erro
 	return stdout, stderr, err
 }
 
+// Execute runs the given script in a shell.
 func Execute(script string) error {
 	cmdl := exec.Command("sh", "-c", script)
 	if _, _, err := RunCommandWithStdoutStderr(cmdl); err != nil {