Improve documentation

5 files changed, 33 insertions, 19 deletions

diff --git a/client/go/cmd/clone.go b/client/go/cmd/clone.go
index 5bd6b147ffa..8d4b382db76 100644
--- a/client/go/cmd/clone.go
+++ b/client/go/cmd/clone.go
@@ -30,9 +30,10 @@ func init() {
 
 var cloneCmd = &cobra.Command{
 	// TODO: "application" and "list" subcommands?
-	Use:     "clone",
-	Short:   "Create files and directory structure for a new Vespa application from a template",
+	Use:     "clone <sample-application-path> <target-directory>",
+	Short:   "Create files and directory structure for a new Vespa application from a sample application",
 	Example: "$ vespa clone vespa-cloud/album-recommendation my-app",
+	Long:    "Creates an application package file structure by copying a sample application\nfrom https://github.com/vespa-engine/sample-apps",
 	Args:    cobra.ExactArgs(2),
 	Run: func(cmd *cobra.Command, args []string) {
 		cloneApplication(args[0], args[1])
diff --git a/client/go/cmd/config.go b/client/go/cmd/config.go
index 544c95aa9f1..edf1283b3b9 100644
--- a/client/go/cmd/config.go
+++ b/client/go/cmd/config.go
@@ -41,7 +41,7 @@ var configCmd = &cobra.Command{
 }
 
 var setConfigCmd = &cobra.Command{
-	Use:     "set option value",
+	Use:     "set <option> <value>",
 	Short:   "Set a configuration option.",
 	Example: "$ vespa config set target cloud",
 	Args:    cobra.ExactArgs(2),
@@ -55,7 +55,7 @@ var setConfigCmd = &cobra.Command{
 }
 
 var getConfigCmd = &cobra.Command{
-	Use:     "get option",
+	Use:     "get <option>",
 	Short:   "Get a configuration option",
 	Example: "$ vespa config get target",
 	Args:    cobra.MaximumNArgs(1),
diff --git a/client/go/cmd/deploy.go b/client/go/cmd/deploy.go
index 048082d2733..a50b5dcefe8 100644
--- a/client/go/cmd/deploy.go
+++ b/client/go/cmd/deploy.go
@@ -24,13 +24,13 @@ var (
 
 func init() {
 	rootCmd.AddCommand(deployCmd)
-	rootCmd.AddCommand(prepareCmd)
-	rootCmd.AddCommand(activateCmd)
+	// rootCmd.AddCommand(prepareCmd)
+	// rootCmd.AddCommand(activateCmd)
 	deployCmd.PersistentFlags().StringVarP(&zoneArg, zoneFlag, "z", "dev.aws-us-east-1c", "The zone to use for deployment")
 }
 
 var deployCmd = &cobra.Command{
-	Use:   "deploy",
+	Use:   "deploy <application-directory>",
 	Short: "Deploy (prepare and activate) an application package",
 	Args:  cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
@@ -83,7 +83,7 @@ var deployCmd = &cobra.Command{
 }
 
 var prepareCmd = &cobra.Command{
-	Use:   "prepare",
+	Use:   "prepare <application-directory>",
 	Short: "Prepare an application package for activation",
 	Args:  cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
diff --git a/client/go/cmd/document.go b/client/go/cmd/document.go
index 89ee2515cc6..a709da222bd 100644
--- a/client/go/cmd/document.go
+++ b/client/go/cmd/document.go
@@ -22,8 +22,15 @@ func init() {
 }
 
 var documentCmd = &cobra.Command{
-	Use:     "document",
-	Short:   "Issues the document operation in the given file to Vespa",
+	Use:   "document <json-file>",
+	Short: "Issue a document operation to Vespa",
+	Long: `Issues the document operation in a file to Vespa.
+The operation must be on the format documented in
+https://docs.vespa.ai/en/reference/document-json-format.html#document-operations
+When this returns Success, the document is guaranteed to be visible in any
+subsequent get or query operation.
+To feed with high throughput, https://docs.vespa.ai/en/vespa-feed-client.html
+should be used instead of this.`,
 	Example: `$ vespa document src/test/resources/A-Head-Full-of-Dreams.json`,
 	Args:    cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
@@ -32,8 +39,11 @@ var documentCmd = &cobra.Command{
 }
 
 var documentPutCmd = &cobra.Command{
-	Use:   "put",
-	Short: "Writes the document in the given file to Vespa",
+	Use:   "put [<id>] <json-file>",
+	Short: "Writes a document to Vespa",
+	Long:  `Writes the document in the given file to Vespa.
+If the document already exists, all its values will be replaced by this document.
+If the document id is specified both as an argument and in the file the argument takes precedence.`,
 	Args:  cobra.RangeArgs(1, 2),
 	Example: `$ vespa document put src/test/resources/A-Head-Full-of-Dreams.json
 $ vespa document put id:mynamespace:music::a-head-full-of-dreams src/test/resources/A-Head-Full-of-Dreams.json`,
@@ -47,8 +57,10 @@ $ vespa document put id:mynamespace:music::a-head-full-of-dreams src/test/resour
 }
 
 var documentUpdateCmd = &cobra.Command{
-	Use:   "update",
-	Short: "Modifies some fields of an existing document as specified in the given file",
+	Use:   "update [<id>] <json-file>",
+	Short: "Modifies some fields of an existing document",
+	Long:  `Updates the values of the fields given in a json file as specified in the file.
+If the document id is specified both as an argument and in the file the argument takes precedence.`,
 	Args:  cobra.RangeArgs(1, 2),
 	Example: `$ vespa document update src/test/resources/A-Head-Full-of-Dreams-Update.json
 $ vespa document update id:mynamespace:music::a-head-full-of-dreams src/test/resources/A-Head-Full-of-Dreams.json`,
@@ -62,8 +74,10 @@ $ vespa document update id:mynamespace:music::a-head-full-of-dreams src/test/res
 }
 
 var documentRemoveCmd = &cobra.Command{
-	Use:   "remove",
+	Use:   "remove <id or json.file>",
 	Short: "Removes a document from Vespa",
+	Long:  `Removes the document specified either as a document id or given in the json file.
+If the document id is specified both as an argument and in the file the argument takes precedence.`,
 	Args:  cobra.ExactArgs(1),
 	Example: `$ vespa document remove src/test/resources/A-Head-Full-of-Dreams-Remove.json
 $ vespa document remove id:mynamespace:music::a-head-full-of-dreams`,
@@ -77,7 +91,7 @@ $ vespa document remove id:mynamespace:music::a-head-full-of-dreams`,
 }
 
 var documentGetCmd = &cobra.Command{
-	Use:   "get",
+	Use:   "get <id>",
 	Short: "Gets a document",
 	Args:  cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
diff --git a/client/go/cmd/root.go b/client/go/cmd/root.go
index e48bb74c97f..1723f2cfa80 100644
--- a/client/go/cmd/root.go
+++ b/client/go/cmd/root.go
@@ -15,12 +15,11 @@ import (
 )
 
 var (
-	// global flags
 	// TODO: add timeout flag
 	// TODO: add flag to show http request made
 	rootCmd = &cobra.Command{
-		Use:   "vespa",
-		Short: "A command-line tool for working with Vespa instances",
+		Use:   "vespa <command>",
+		Short: "The command-line tool for Vespa",
 	}
 	color          aurora.Aurora
 	targetArg      string