updating usage notes and multi-word formatted flags

8 files changed, 60 insertions, 58 deletions

diff --git a/README.md b/README.md
index 2272956..74160f1 100644
--- a/README.md
+++ b/README.md
@@ -61,24 +61,23 @@ required of clients connecting to a Ponzu server to make HTTP/2 requests.
 ## Usage
 
 ```bash
-$ ponzu [flags] command <params>
+$ ponzu command [flags] <params>
 ```
 
 ## Commands
 
 ### new
 
-Creates a 'ponzu' directory, or one by 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.
+Creates a project 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.
 
 Example:
 ```bash
-$ ponzu new myProject
-> New ponzu project created at $GOPATH/src/myProject
+$ ponzu new github.com/nilslice/proj
+> New ponzu project created at $GOPATH/src/github.com/nilslice/proj
 ```
 
 Errors will be reported, but successful commands return nothing.
@@ -147,13 +146,13 @@ the necessary files from your workspace into the vendored directory, and
 will build/compile the project to then be run. 
 
 Optional flags:
-- `-gocmd` sets the binary used when executing `go build` within `ponzu` build step
+- `--gocmd` sets the binary used when executing `go build` within `ponzu` build step
 
 Example:
 ```bash
 $ ponzu build
 (or)
-$ ponzu -gocmd=go1.8rc1 build # useful for testing
+$ ponzu build --gocmd=go1.8rc1 # useful for testing
 ```
 
 Errors will be reported, but successful build commands return nothing.
@@ -169,24 +168,24 @@ if the server should utilize TLS encryption - served over HTTPS, which is
 automatically managed using Let's Encrypt (https://letsencrypt.org) 
 
 Optional flags:
-- `-port` sets the port on which the server listens for HTTP requests [defaults to 8080]
-- `-httpsport` sets the port on which the server listens for HTTPS requests [defaults to 443]
+- `--port` sets the port on which the server listens for HTTP requests [defaults to 8080]
+- `--https-port` sets the port on which the server listens for HTTPS requests [defaults to 443]
 - `--https` enables auto HTTPS management via Let's Encrypt (port is always 443)
-- `--devhttps` generates self-signed SSL certificates for development-only (port is 10443)
+- `--dev-https` generates self-signed SSL certificates for development-only (port is 10443)
 
 Example: 
 ```bash
 $ 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
 (or)
-$ ponzu --devhttps run
+$ ponzu --dev-https run
 ```
-Defaults to `$ ponzu -port=8080 run admin,api` (running Admin & API on port 8080, without TLS)
+Defaults to `$ ponzu 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
@@ -233,10 +232,10 @@ print the version of the Ponzu CLI you have installed.
 Example:
 ```bash
 $ 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
 ```
 
 ---
@@ -283,14 +282,14 @@ $ git push origin ponzu-dev
 ```
 
 **Note:** if you intend to work on your own fork and contribute from it, you will
-need to also pass `-fork=path/to/your/fork` (using OS-standard filepath structure),
+need to also pass `--fork=path/to/your/fork` (using OS-standard filepath structure),
 where `path/to/your/fork` _must_ be within `$GOPATH/src`, and you are working from a branch
 called `ponzu-dev`. 
 
 For example: 
 ```bash
 # ($GOPATH/src is implied in the fork path, do not add it yourself)
-$ ponzu --dev -fork=github.com/nilslice/ponzu new /path/to/new/project
+$ ponzu new --dev --fork=github.com/nilslice/ponzu /path/to/new/project
 ```
 
 
@@ -307,6 +306,7 @@ $ ponzu --dev -fork=github.com/nilslice/ponzu new /path/to/new/project
 - [github.com/tidwall/gjson](https://github.com/tidwall/gjson)
 - [github.com/tidwall/sjson](https://github.com/tidwall/sjson)
 - [github.com/boltdb/bolt](https://github.com/boltdb/bolt)
+- [github.com/spf13/cobra](github.com/spf13/cobra)
 - [Materialnote Editor](https://github.com/Cerealkillerway/materialNote)
 - [Materialize.css](https://github.com/Dogfalo/materialize)
 - [jQuery](https://github.com/jquery/jquery)
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 {