From a0199341696d04204f33df7b88ea387a2b7d1247 Mon Sep 17 00:00:00 2001
From: Janne Valkealahti <janne.valkealahti@gmail.com>
Date: Tue, 14 Jun 2022 21:25:01 +0100
Subject: [PATCH] Update docs

- Document option label
- Relates #433
---
 .../asciidoc/using-shell-options-label.adoc   | 37 +++++++++++++++++++
 .../main/asciidoc/using-shell-options.adoc    |  2 +
 .../shell/docs/OptionSnippets.java            | 11 ++++++
 3 files changed, 50 insertions(+)
 create mode 100644 spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc

diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc
new file mode 100644
index 00000000..92d83687
--- /dev/null
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc
@@ -0,0 +1,37 @@
+[[using-shell-options-label]]
+==== Label
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+_Option Label_ has no functional behaviour within a shell itself other than
+what a default `help` command outputs. Within a command documentation
+a type of an option is documented but this is not always super useful. Thus
+you may want to give better descriptive word for an option.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/OptionSnippets.java[tag=option-registration-label]
+----
+====
+
+Defining label is then shown in `help`.
+
+====
+[source, bash]
+----
+my-shell:>help mycommand
+NAME
+       mycommand -
+
+SYNOPSIS
+       mycommand --arg1 String --arg2 MYLABEL
+
+OPTIONS
+       --arg1 String
+       [Optional]
+
+       --arg2 MYLABEL
+       [Optional]
+
+----
+====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
index bf079c54..85691ef6 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
@@ -18,3 +18,5 @@ include::using-shell-options-optional.adoc[]
 include::using-shell-options-default.adoc[]
 
 include::using-shell-options-validation.adoc[]
+
+include::using-shell-options-label.adoc[]
diff --git a/spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionSnippets.java b/spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionSnippets.java
index 3eae5548..e3142c47 100644
--- a/spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionSnippets.java
+++ b/spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionSnippets.java
@@ -163,6 +163,17 @@ public class OptionSnippets {
 			.build();
 		// end::option-registration-default[]
 
+		// tag::option-registration-label[]
+		CommandRegistration.builder()
+			.withOption()
+				.longNames("arg1")
+				.and()
+			.withOption()
+				.longNames("arg2")
+				.label("MYLABEL")
+				.and()
+			.build();
+		// end::option-registration-label[]
 	}
 
 }