kubectl: rewrite docstrings in several files

Fixing inaccuracies and clarifying in the case of ambiguities.

pkg/kubectl/cmd/cp.go

@@ -35,14 +35,15 @@ import (
 
 var (
 	cp_example = templates.Examples(i18n.T(`
-	    # !!!Important Note!!!
-	    # Requires that the 'tar' binary is present in your container
-	    # image.  If 'tar' is not present, 'kubectl cp' will fail.
+		# !!!Important Note!!!
+		# Requires that the 'tar' binary is present in your container
+		# image.  If 'tar' is not present, 'kubectl cp' will fail.
 
-	    # Copy /tmp/foo_dir local directory to /tmp/bar_dir in a remote pod in the default namespace
+
+		# Copy /tmp/foo_dir local directory to /tmp/bar_dir in a remote pod in the default namespace
 		kubectl cp /tmp/foo_dir <some-pod>:/tmp/bar_dir
 
-        # Copy /tmp/foo local file to /tmp/bar in a remote pod in a specific container
+		# Copy /tmp/foo local file to /tmp/bar in a remote pod in a specific container
 		kubectl cp /tmp/foo <some-pod>:/tmp/bar -c <specific-container>
 
 		# Copy /tmp/foo local file to /tmp/bar in a remote pod in namespace <some-namespace>
@@ -52,8 +53,8 @@ var (
 		kubectl cp <some-namespace>/<some-pod>:/tmp/foo /tmp/bar`))
 
 	cpUsageStr = dedent.Dedent(`
-	    expected 'cp <file-spec-src> <file-spec-dest> [-c container]'.
-	    <file-spec> is:
+		expected 'cp <file-spec-src> <file-spec-dest> [-c container]'.
+		<file-spec> is:
 		[namespace/]pod-name:/file/path for a remote file
 		/file/path for a local file`)
 )

pkg/kubectl/cmd/create.go

@@ -40,7 +40,7 @@ type CreateOptions struct {
 
 var (
 	create_long = templates.LongDesc(i18n.T(`
-		Create a resource by filename or stdin.
+		Create a resource from a file or from stdin.
 
 		JSON and YAML formats are accepted.`))
 
@@ -60,7 +60,7 @@ func NewCmdCreate(f cmdutil.Factory, out, errOut io.Writer) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "create -f FILENAME",
-		Short:   i18n.T("Create a resource by filename or stdin"),
+		Short:   i18n.T("Create a resource from a file or from stdin."),
 		Long:    create_long,
 		Example: create_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/create_deployment.go

@@ -38,7 +38,9 @@ var (
     kubectl create deployment my-dep --image=busybox`))
 )
 
-// NewCmdCreateDeployment is a macro command to create a new deployment
+// NewCmdCreateDeployment is a macro command to create a new deployment.
+// This command is better known to users as `kubectl create deployment`.
+// Note that this command overlaps significantly with the `kubectl run` command.
 func NewCmdCreateDeployment(f cmdutil.Factory, cmdOut, cmdErr io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "deployment NAME --image=image [--dry-run]",

pkg/kubectl/doc.go

@@ -14,7 +14,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package kubectl is a set of libraries that are used by the kubectl command line tool.
-// They are separated out into a library to support unit testing.  Most functionality should
-// be included in this package, and the main kubectl should really just be an entry point.
+// Package kubectl provides the functions used by the kubectl command line tool
+// under k8s.io/kubernetes/cmd. The functions are kept in this package to better
+// support unit testing. The main() method for kubectl is only an entry point
+// and should contain no functionality.
 package kubectl // import "k8s.io/kubernetes/pkg/kubectl"

pkg/kubectl/generate.go

@@ -35,7 +35,9 @@ type GeneratorParam struct {
 	Required bool
 }
 
-// Generator is an interface for things that can generate API objects from input parameters.
+// Generator is an interface for things that can generate API objects from input
+// parameters. One example is the "expose" generator that is capable of exposing
+// new replication controllers and services, among other things.
 type Generator interface {
 	// Generate creates an API object given a set of parameters
 	Generate(params map[string]interface{}) (runtime.Object, error)

pkg/kubectl/kubectl.go

@@ -212,7 +212,10 @@ func parseFileSource(source string) (keyName, filePath string, err error) {
 	}
 }
 
-// parseLiteralSource parses the source key=val pair
+// parseLiteralSource parses the source key=val pair into its component pieces.
+// This functionality is distinguished from strings.SplitN(source, "=", 2) since
+// it returns an error in the case of empty keys, values, or a missing equals
+// sign.
 func parseLiteralSource(source string) (keyName, value string, err error) {
 	// leading equal is invalid
 	if strings.Index(source, "=") == 0 {

pkg/kubectl/proxy_server.go

@@ -108,7 +108,8 @@ func (f *FilterServer) accept(method, path, host string) bool {
 	return false
 }
 
-// Make a copy of f which passes requests along to the new delegate.
+// HandlerFor makes a shallow copy of f which passes its requests along to the
+// new delegate.
 func (f *FilterServer) HandlerFor(delegate http.Handler) *FilterServer {
 	f2 := *f
 	f2.delegate = delegate

pkg/kubectl/stop.go

@@ -46,11 +46,12 @@ const (
 	Timeout  = time.Minute * 5
 )
 
-// A Reaper handles terminating an object as gracefully as possible.
-// timeout is how long we'll wait for the termination to be successful
-// gracePeriod is time given to an API object for it to delete itself cleanly,
-// e.g., pod shutdown. It may or may not be supported by the API object.
+// A Reaper terminates an object as gracefully as possible.
 type Reaper interface {
+	// Stop a given object within a namespace. timeout is how long we'll
+	// wait for the termination to be successful. gracePeriod is time given
+	// to an API object for it to delete itself cleanly (e.g., pod
+	// shutdown). It may or may not be supported by the API object.
 	Stop(namespace, name string, timeout time.Duration, gracePeriod *metav1.DeleteOptions) error
 }