From 079351fcae1611b2cd20b477a5d23966c10c353d Mon Sep 17 00:00:00 2001
From: Gilbertsoft <25326036+gilbertsoft@users.noreply.github.com>
Date: Wed, 16 Sep 2020 23:27:05 +0200
Subject: [PATCH] Allow multiline examples for custom commands (#2495)

---
 cmd/ddev/cmd/commands.go                      |  2 +-
 cmd/ddev/cmd/commands_test.go                 | 21 +++++++++++++------
 .../project_commands/host/testhostcmd         |  2 +-
 docs/users/extend/custom-commands.md          | 10 +++++++++
 4 files changed, 27 insertions(+), 8 deletions(-)

diff --git a/cmd/ddev/cmd/commands.go b/cmd/ddev/cmd/commands.go
index 7ee1d58bfcf..d1f60cf3239 100644
--- a/cmd/ddev/cmd/commands.go
+++ b/cmd/ddev/cmd/commands.go
@@ -108,7 +108,7 @@ func addCustomCommands(rootCmd *cobra.Command) error {
 					usage = val
 				}
 				if val, ok := directives["Example"]; ok {
-					example = val
+					example = "  " + strings.ReplaceAll(val, `\n`, "\n  ")
 				}
 				if val, ok := directives["ProjectTypes"]; ok {
 					projectTypes = val
diff --git a/cmd/ddev/cmd/commands_test.go b/cmd/ddev/cmd/commands_test.go
index 301e81ed9a0..6250f53c0f6 100644
--- a/cmd/ddev/cmd/commands_test.go
+++ b/cmd/ddev/cmd/commands_test.go
@@ -2,6 +2,13 @@ package cmd
 
 import (
 	"fmt"
+	"os"
+	osexec "os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
 	"github.com/drud/ddev/pkg/ddevapp"
 	"github.com/drud/ddev/pkg/exec"
 	"github.com/drud/ddev/pkg/fileutil"
@@ -10,12 +17,6 @@ import (
 	"github.com/drud/ddev/pkg/util"
 	asrt "github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"os"
-	osexec "os/exec"
-	"path/filepath"
-	"strings"
-	"testing"
-	"time"
 )
 
 // TestCustomCommands does basic checks to make sure custom commands work OK.
@@ -111,6 +112,14 @@ func TestCustomCommands(t *testing.T) {
 		assert.Contains(out, fmt.Sprintf("%s was executed with args=hostarg1 hostarg2 --hostflag1 on host %s", c, expectedHost))
 	}
 
+	// Test line breaks in examples
+	c := "testhostcmd"
+	args := []string{c, "-h"}
+	out, err = exec.RunCommand(DdevBin, args)
+	assert.NoError(err, "Failed to run ddev %s %v", c, args)
+	assert.Contains(out, "Examples:\n  ddev testhostcmd\n  ddev testhostcmd -h")
+
+	// Provide app configuration
 	app.Type = nodeps.AppTypePHP
 	err = app.WriteConfig()
 	assert.NoError(err)
diff --git a/cmd/ddev/cmd/testdata/TestCustomCommands/project_commands/host/testhostcmd b/cmd/ddev/cmd/testdata/TestCustomCommands/project_commands/host/testhostcmd
index da6b3c5a84b..97e285d13fb 100755
--- a/cmd/ddev/cmd/testdata/TestCustomCommands/project_commands/host/testhostcmd
+++ b/cmd/ddev/cmd/testdata/TestCustomCommands/project_commands/host/testhostcmd
@@ -2,6 +2,6 @@
 
 ## Description: testhostcmd project
 ## Usage: testhostcmd
-## Example: "ddev testhostcmd"
+## Example: ddev testhostcmd\nddev testhostcmd -h
 
 echo "testhostcmd was executed with args=$@ on host $(hostname)"
diff --git a/docs/users/extend/custom-commands.md b/docs/users/extend/custom-commands.md
index 6d69fca3b7e..2bd17dfdfb1 100644
--- a/docs/users/extend/custom-commands.md
+++ b/docs/users/extend/custom-commands.md
@@ -102,6 +102,16 @@ Useful variables for container scripts are:
 * DDEV_WEBSERVER_TYPE: nginx-fpm, apache-fpm
 * IS_DDEV_PROJECT: if set to "true" it means that php is running under DDEV
 
+### Annotations supported
+
+The custom commands support various annotations in the header which are used to provide additional information about the command to the user:
+
+* Description
+* Usage
+* Example (use `\n` to force a line break)
+* ProjectTypes
+* OSTypes
+
 ### Known Windows OS issues
 
 * **Line Endings**: If you are editing a custom command which will run in a container, it must have LF line endings (not traditional Windows CRLF line endings). Remember that a custom command in a container is a script that must execute in a Linux environmet.