docs: improve rendering of "alternatives" schema type

docs/reference/config.md

@@ -136,9 +136,9 @@ A key/value map of variables that modules can reference when using this environm
 
 A list of environments to configure for the project.
 
-| Type           | Required |
-| -------------- | -------- |
-| `alternatives` | No       |
+| Type                            | Required |
+| ------------------------------- | -------- |
+| `array[object] | array[string]` | No       |
 
 Example:
 

garden-service/src/docs/config.ts

@@ -143,8 +143,11 @@ function normalizeKeyDescription(description: Description): NormalizedDescriptio
   let hasChildren: boolean = false
   let arrayType: string | undefined
   const { type } = description
+  const formattedType = formatType(description)
+
   const children = type === "object" && Object.entries(description.children || {})
   const items = type === "array" && description.items
+
   if (children && children.length > 0) {
     hasChildren = true
   } else if (items && items.length > 0) {
@@ -164,7 +167,6 @@ function normalizeKeyDescription(description: Description): NormalizedDescriptio
   }
 
   const formattedName = type === "array" ? `${description.name}[]` : description.name
-  const formattedType = (type === "array" && arrayType ? `array[${arrayType}]` : type) || ""
 
   return {
     ...description,
@@ -178,6 +180,22 @@ function normalizeKeyDescription(description: Description): NormalizedDescriptio
   }
 }
 
+function formatType(description: Description) {
+  const { type } = description
+  const items = type === "array" && description.items
+
+  if (items && items.length > 0) {
+    // We don't consider an array of primitives as children
+    const arrayType = items[0].type
+    return `array[${arrayType}]`
+  } else if (type === "alternatives") {
+    // returns e.g. "string|number"
+    return uniq(description.alternatives.map(formatType)).join(" | ")
+  } else {
+    return type || ""
+  }
+}
+
 export function getDefaultValue(description: Joi.Description) {
   const defaultSpec = get(description, "flags.default")