Refactor option basic docs

- Document better a relationship between annotation,
  legacy annotation and programmatic registration.
- Relates #637

spring-shell-docs/src/main/asciidoc/using-shell-options-basics-annotation.adoc

@@ -0,0 +1,13 @@
+[[using-shell-options-basics-annotation]]
+==== Annotation
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+`Option` annotation can be used to define an option name if you
+don't want it to be same as argument name.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/OptionSnippets.java[tag=option-with-option-annotation]
+----
+====

spring-shell-docs/src/main/asciidoc/using-shell-options-basics-legacyannotation.adoc

@@ -1,10 +1,7 @@
-[[using-shell-options-definition]]
-=== Definition
+[[using-shell-options-basics-legacyannotation]]
+==== Legacy Annotation
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
-Options can be defined within a target method as annotations in a method arguments
-or with programmatically with `CommandRegistration`.
-
 Having a target method with argument is automatically registered with a matching
 argument name.
 
@@ -15,16 +12,6 @@ include::{snippets}/OptionSnippets.java[tag=option-without-annotation]
 ----
 ====
 
-`Option` annotation can be used to define an option name if you
-don't want it to be same as argument name.
-
-====
-[source, java, indent=0]
-----
-include::{snippets}/OptionSnippets.java[tag=option-with-option-annotation]
-----
-====
-
 `@ShellOption` annotation can be used to define an option name if you
 don't want it to be same as argument name.
 
@@ -44,12 +31,3 @@ from _ShellMethod#prefix_.
 include::{snippets}/OptionSnippets.java[tag=option-with-annotation-without-prefix]
 ----
 ====
-
-Programmatic way with `CommandRegistration` is to use method adding a long name.
-
-====
-[source, java, indent=0]
-----
-include::{snippets}/OptionSnippets.java[tag=option-registration-longarg]
-----
-====

spring-shell-docs/src/main/asciidoc/using-shell-options-basics-registration.adoc

@@ -0,0 +1,18 @@
+[[using-shell-options-basics-registration]]
+==== Registration
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+Programmatic way with `CommandRegistration` is to use `withOption` to define
+an option.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/OptionSnippets.java[tag=option-registration-longarg]
+----
+====
+
+`CommandRegistration` can be defined as a bean or manually registered
+with a `CommandCatalog`.
+
+NOTE: Check below sections for other option types, i.e. short format.

spring-shell-docs/src/main/asciidoc/using-shell-options-basics.adoc

@@ -0,0 +1,13 @@
+[[using-shell-options-basics]]
+=== Basics
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+This section gives a generic idea how an option can be defined. Following
+sections, beyond basics, discuss more about how various option behaviour
+can be accomplished for a particular use case.
+
+include::using-shell-options-basics-annotation.adoc[]
+
+include::using-shell-options-basics-registration.adoc[]
+
+include::using-shell-options-basics-legacyannotation.adoc[]

spring-shell-docs/src/main/asciidoc/using-shell-options.adoc

@@ -3,9 +3,21 @@
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 Command line arguments can be separated into options and positional parameters.
-Following sections describes features how options are defined and used.
+Following sections describes features how options are defined and used. We first
+go through some basics about using options and then go into details about
+various ways how options and arguments works.
 
-include::using-shell-options-definition.adoc[]
+Generally speaking an _option_ is something after a commands prefixed with
+either `-` or `--`. An _option_ can either have a value or not depending
+on its context.
+
+Options can be defined with a target method using annotations with a method
+arguments or with programmatically using `CommandRegistration`.
+
+NOTE: In below sections `@ShellOption` refer to a _legacy annotation model_
+and `@Option` refer to an _annotation model_.
+
+include::using-shell-options-basics.adoc[]
 
 include::using-shell-options-short.adoc[]
 

spring-shell-docs/src/test/java/org/springframework/shell/docs/OptionSnippets.java

@@ -21,6 +21,7 @@ import org.springframework.context.annotation.Bean;
 import org.springframework.shell.command.CommandRegistration;
 import org.springframework.shell.command.CommandRegistration.OptionArity;
 import org.springframework.shell.command.CommandRegistration.OptionNameModifier;
+import org.springframework.shell.command.annotation.Command;
 import org.springframework.shell.command.annotation.Option;
 import org.springframework.shell.standard.ShellMethod;
 import org.springframework.shell.standard.ShellOption;
@@ -29,7 +30,8 @@ public class OptionSnippets {
 
 	class Dump1Legacy {
 		// tag::option-with-annotation[]
-		public String example(@ShellOption(value = { "--argx" }) String arg1) {
+		@ShellMethod
+		public String example(@ShellOption(value = { "--arg" }) String arg1) {
 			return "Hello " + arg1;
 		}
 		// end::option-with-annotation[]
@@ -37,7 +39,8 @@ public class OptionSnippets {
 
 	class Dump1 {
 		// tag::option-with-option-annotation[]
-		public String example(@Option(longNames = "argx") String arg1) {
+		@Command
+		public String example(@Option(longNames = "arg") String arg1) {
 			return "Hello " + arg1;
 		}
 		// end::option-with-option-annotation[]
@@ -45,7 +48,8 @@ public class OptionSnippets {
 
 	class Dump7 {
 		// tag::option-with-annotation-without-prefix[]
-		public String example(@ShellOption(value = { "argx" }) String arg1) {
+		@ShellMethod
+		public String example(@ShellOption(value = { "arg" }) String arg1) {
 			return "Hello " + arg1;
 		}
 		// end::option-with-annotation-without-prefix[]
@@ -53,6 +57,7 @@ public class OptionSnippets {
 
 	class Dump2 {
 		// tag::option-without-annotation[]
+		@ShellMethod
 		public String example(String arg1) {
 			return "Hello " + arg1;
 		}
@@ -99,10 +104,11 @@ public class OptionSnippets {
 		// end::option-with-annotation-default[]
 	}
 
+	@SuppressWarnings("unused")
 	public void dump1() {
 
 		// tag::option-registration-longarg[]
-		CommandRegistration.builder()
+		CommandRegistration registration = CommandRegistration.builder()
 			.withOption()
 				.longNames("arg1")
 				.and()