updating usage notes and multi-word formatted flags

7 files changed, 37 insertions, 35 deletions

diff --git a/cmd/ponzu/add.go b/cmd/ponzu/add.go
index 30cf168..f4b9fea 100644
--- a/cmd/ponzu/add.go
+++ b/cmd/ponzu/add.go
@@ -12,17 +12,16 @@ import (
 )
 
 var addCmd = &cobra.Command{
-	Use:     "add <repo>",
+	Use:     "add <import path>",
 	Aliases: []string{"a"},
 	Short:   "Downloads addon from specified import path",
 	Long: `Downloads addon from specified import path to $GOPATH/src and copys it to the
-current project's ./addons directory. Must be called from within a
-Ponzu project directory.`,
+current project's addons directory. Must be called from within a Ponzu project directory.`,
 	Example: `$ ponzu add github.com/bosssauce/fbscheduler`,
 	RunE: func(cmd *cobra.Command, args []string) error {
-		// expecting two args, add and the go gettable package uri
+		// expecting two args, add/a and the go gettable package uri
 		if len(args) < 1 {
-			return errors.New("repo not given")
+			return errors.New("no import path provided")
 		}
 
 		return getAddon(args[0])
diff --git a/cmd/ponzu/build.go b/cmd/ponzu/build.go
index 0037355..d0f82eb 100644
--- a/cmd/ponzu/build.go
+++ b/cmd/ponzu/build.go
@@ -35,7 +35,7 @@ func buildPonzuServer() error {
 }
 
 var buildCmd = &cobra.Command{
-	Use:   "build",
+	Use:   "build [flags]",
 	Short: "build will build/compile the project to then be run.",
 	Long: `From within your Ponzu project directory, running build will copy and move
 the necessary files from your workspace into the vendored directory, and
@@ -47,7 +47,7 @@ project, if testing a different release of Go.
 Errors will be reported, but successful build commands return nothing.`,
 	Example: `$ ponzu build
 (or)
-$ ponzu -gocmd=go1.8rc1 build`,
+$ ponzu build --gocmd=go1.8rc1`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return buildPonzuServer()
 	},
diff --git a/cmd/ponzu/main.go b/cmd/ponzu/main.go
index acbe214..4651b9e 100644
--- a/cmd/ponzu/main.go
+++ b/cmd/ponzu/main.go
@@ -15,14 +15,14 @@ import (
 	"strings"
 	"time"
 
+	_ "github.com/ponzu-cms/ponzu/content"
 	"github.com/ponzu-cms/ponzu/system/admin"
 	"github.com/ponzu-cms/ponzu/system/api"
 	"github.com/ponzu-cms/ponzu/system/api/analytics"
 	"github.com/ponzu-cms/ponzu/system/db"
 	"github.com/ponzu-cms/ponzu/system/tls"
-	"github.com/spf13/cobra"
 
-	_ "github.com/ponzu-cms/ponzu/content"
+	"github.com/spf13/cobra"
 )
 
 var (
@@ -41,17 +41,13 @@ var (
 
 var rootCmd = &cobra.Command{
 	Use: "ponzu",
-	Long: `Ponzu is a powerful and efficient open-source HTTP server framework and CMS. It
-provides automatic, free, and secure HTTP/2 over TLS (certificates obtained via
-[Let's Encrypt](https://letsencrypt.org)), a useful CMS and scaffolding to
-generate set-up code, and a fast HTTP API on which to build modern applications.
-
-Ponzu is released under the BSD-3-Clause license (see LICENSE).
+	Long: `Ponzu is an open-source HTTP server framework and CMS, released under 
+the BSD-3-Clause license.
 (c) 2016 - ` + year + ` Boss Sauce Creative, LLC`,
 }
 
 var runCmd = &cobra.Command{
-	Use:   "run <service(,service)>",
+	Use:   "run [flags] <service(,service)>",
 	Short: "starts the 'ponzu' HTTP server for the JSON API and or Admin System.",
 	Long: `Starts the 'ponzu' HTTP server for the JSON API, Admin System, or both.
 The segments, separated by a comma, describe which services to start, either
@@ -59,7 +55,7 @@ The segments, separated by a comma, describe which services to start, either
 if the server should utilize TLS encryption - served over HTTPS, which is
 automatically managed using Let's Encrypt (https://letsencrypt.org)
 
-Defaults to '-port=8080 run admin,api' (running Admin & API on port 8080, without TLS)
+Defaults to 'run -port=8080 admin,api' (running Admin & API on port 8080, without TLS)
 
 Note:
 Admin and API cannot run on separate processes unless you use a copy of the
@@ -68,11 +64,11 @@ to run the Admin and API on separate processes, you must call them with the
 'ponzu' command independently.`,
 	Example: `$ ponzu run
 (or)
-$ ponzu -port=8080 --https run admin,api
+$ ponzu run --port=8080 --https admin,api
 (or)
 $ ponzu run admin
 (or)
-$ ponzu -port=8888 run api`,
+$ ponzu run --port=8888 api`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var addTLS string
 		if https {
@@ -108,13 +104,15 @@ $ ponzu -port=8888 run api`,
 	},
 }
 
+// ErrWrongOrMissingService informs a user that the services to run must be
+// explicitly specified when serve is called
 var ErrWrongOrMissingService = errors.New("To execute 'ponzu serve', " +
 	"you must specify which service to run.")
 
 var serveCmd = &cobra.Command{
-	Use:     "serve <service,service>",
+	Use:     "serve [flags] <service,service>",
 	Aliases: []string{"s"},
-	Short:   "actually run the server",
+	Short:   "actually run the server (serve is wrapped by the run command)",
 	Hidden:  true,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) == 0 {
@@ -179,9 +177,9 @@ var serveCmd = &cobra.Command{
 func init() {
 	for _, cmd := range []*cobra.Command{runCmd, serveCmd} {
 		cmd.Flags().IntVar(&port, "port", 8080, "port for ponzu to bind its HTTP listener")
-		cmd.Flags().IntVar(&httpsport, "httpsport", 443, "port for ponzu to bind its HTTPS listener")
+		cmd.Flags().IntVar(&httpsport, "http-sport", 443, "port for ponzu to bind its HTTPS listener")
 		cmd.Flags().BoolVar(&https, "https", false, "enable automatic TLS/SSL certificate management")
-		cmd.Flags().BoolVar(&devhttps, "devhttps", false, "[dev environment] enable automatic TLS/SSL certificate management")
+		cmd.Flags().BoolVar(&devhttps, "dev-https", false, "[dev environment] enable automatic TLS/SSL certificate management")
 	}
 
 	RegisterCmdlineCommand(runCmd)
diff --git a/cmd/ponzu/new.go b/cmd/ponzu/new.go
index 9911931..2f16a53 100644
--- a/cmd/ponzu/new.go
+++ b/cmd/ponzu/new.go
@@ -11,22 +11,24 @@ import (
 )
 
 var newCmd = &cobra.Command{
-	Use:   "new [projectName]",
-	Short: "creates a 'ponzu' directory or the name supplied as a parameter",
-	Long: `Creates a 'ponzu' directory or one by the name supplied as a parameter
+	Use:   "new [flags] <project name>",
+	Short: "creates a project directory of the name supplied as a parameter",
+	Long: `Creates aproject  directory of the name supplied as a parameter
 immediately following the 'new' option in the $GOPATH/src directory. Note:
 'new' depends on the program 'git' and possibly a network connection. If
 there is no local repository to clone from at the local machine's $GOPATH,
 'new' will attempt to clone the 'github.com/ponzu-cms/ponzu' package from
-over the network.
-
-Errors will be reported, but successful commands return nothing.`,
-	Example: `$ ponzu new myProject
-> New ponzu project created at $GOPATH/src/myProject`,
+over the network.`,
+	Example: `$ ponzu new github.com/nilslice/proj
+> New ponzu project created at $GOPATH/src/github.com/nilslice/proj`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		projectName := "ponzu"
 		if len(args) > 0 {
 			projectName = args[0]
+		} else {
+			msg := "Please provide a project name."
+			msg += "\nThis will create a directory within your $GOPATH/src."
+			return fmt.Errorf("%s", msg)
 		}
 		return newProjectInDir(projectName)
 	},
diff --git a/cmd/ponzu/upgrade.go b/cmd/ponzu/upgrade.go
index 9671c79..ee9c966 100644
--- a/cmd/ponzu/upgrade.go
+++ b/cmd/ponzu/upgrade.go
@@ -13,7 +13,7 @@ import (
 var upgradeCmd = &cobra.Command{
 	Use:   "upgrade",
 	Short: "upgrades your project to the current ponzu version",
-	Long: `Will backup your own custom project code (like content, addons, uploads, etc) so
+	Long: `Will backup your own custom project code (like content, addons, uploads, etc)
 if necessary. Before running '$ ponzu upgrade', you should update the 'ponzu'
 package by running '$ go get -u github.com/ponzu-cms/ponzu/...'`,
 	Example: `$ ponzu upgrade`,
@@ -25,6 +25,7 @@ package by running '$ go get -u github.com/ponzu-cms/ponzu/...'`,
 		}
 
 		fmt.Println("Only files you added to this directory, 'addons' and 'content' will be preserved.")
+		fmt.Println("Changes you made to Ponzu's internal code will be overwritten.")
 		fmt.Println("Upgrade this project? (y/N):")
 
 		answer, err := getAnswer()
diff --git a/cmd/ponzu/usage.go b/cmd/ponzu/usage.go
index 9a78587..da28b44 100644
--- a/cmd/ponzu/usage.go
+++ b/cmd/ponzu/usage.go
@@ -77,6 +77,8 @@ var helpCmd = &cobra.Command{
 
 var cmds []*cobra.Command
 
+// RegisterCmdlineCommand adds a cobra command to the root command and makes it
+// known to the main package
 func RegisterCmdlineCommand(cmd *cobra.Command) {
 	rootCmd.AddCommand(cmd)
 	cmds = append(cmds, cmd)
diff --git a/cmd/ponzu/version.go b/cmd/ponzu/version.go
index d22d5a4..0e0b133 100644
--- a/cmd/ponzu/version.go
+++ b/cmd/ponzu/version.go
@@ -17,10 +17,10 @@ var versionCmd = &cobra.Command{
 	Long: `Prints the version of Ponzu your project is using. Must be called from
 within a Ponzu project directory.`,
 	Example: `$ ponzu version
-> Ponzu v0.7.1
+> Ponzu v0.8.2
 (or)
-$ ponzu --cli version
-> Ponzu v0.7.2`,
+$ ponzu version --cli
+> Ponzu v0.9.2`,
 	Run: func(cmd *cobra.Command, args []string) {
 		p, err := version(cli)
 		if err != nil {