Update documentation

Author: fmbenhassine

spring-shell-docs/modules/ROOT/nav.adoc

@@ -4,9 +4,7 @@
 * xref:basics/index.adoc[]
 ** xref:basics/reading.adoc[]
 * xref:commands/index.adoc[]
-** xref:commands/registration/index.adoc[]
-** xref:commands/registration/programmatic.adoc[]
-** xref:commands/registration/annotation.adoc[]
+** xref:commands/registration.adoc[]
 ** xref:commands/organize.adoc[]
 ** xref:commands/syntax.adoc[]
 ** xref:commands/validation.adoc[]

spring-shell-docs/modules/ROOT/pages/basics/reading.adoc

@@ -5,8 +5,6 @@
 Throughout this documentation, we make references to configuring something by using
 annotations or programmatic examples.
 
-The annotation model relates to the use of `@Command`.
+The annotation model relates to the use of `@Command` annotation. The programmatic model relates to creating commands using APIs such as `Command.Builder`.
 
-The programmatic model relates to creating commands using APIs such as `Command.Builder`.
-
-These approaches can be mixed in the same application.
+These two approaches can be mixed in the same application.

spring-shell-docs/modules/ROOT/pages/commands/builtin/help.adoc

@@ -10,13 +10,13 @@ Typing `help` + `ENTER` lists all the commands known to the shell and a short de
 [source, bash]
 ----
 my-shell:>help
-AVAILABLE COMMANDS
+Available commands:
 
 Built-In Commands
        help: Display help about available commands
        clear: Clear the shell screen.
        version: Show version info
 ----
 
-Typing `<command> -h` `<command> --help` or  shows more detailed information about a command, including the available parameters, their
+Typing `<command> -h` or `<command> --help` shows more information about a command, including the available parameters, their
 type, whether they are mandatory or not, and other details.

spring-shell-docs/modules/ROOT/pages/commands/index.adoc

@@ -4,7 +4,7 @@
 
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
-In this section, we go through an actual command definition and parsing rules.
+In this section, we go through the actual command definition and parsing rules.
 
 
 

spring-shell-docs/modules/ROOT/pages/commands/registration.adoc

@@ -0,0 +1,63 @@
+[[registration]]
+= Command Registration
+:page-section-summary-toc: 1
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+There are two different ways to define a command, through an annotation model and through a programmatic model:
+
+- In the annotation model, you define your methods in a `@Component` class and the methods with specific annotations.
+- In the programmatic model, you use a more low level approach, defining commands as beans.
+
+[[commands-registration-annotation]]
+== Annotation-Based Registration
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+The `@Command` annotation marks a method as a candidate for command registration.
+In below example a command `example` is defined.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandAnnotationSnippets.java[tag=command-anno-in-method]
+----
+
+TIP: The command name optional, if not provided the method name will be used as command name.
+When the command returns a value, it will be printed to the shell output.
+
+Using a `@Command` will not automatically register command targets, instead it is required to use
+`@EnableCommand` annotations. This model is familiar from other parts  of Spring umbrella and
+provides better flexibility for a user being inclusive rather than exclusive for command targets.
+
+You can define target classes using `@EnableCommand`. It will get picked from all _Configuration_
+classes.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandAnnotationSnippets.java[tag=enablecommand-with-class]
+----
+
+TIP: `@EnableCommand` is not required in a Spring Boot application, as Spring Boot auto-configuration
+will take care of that.
+
+[[commands-registration-programmatic]]
+== Programmatic Registration
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+In the programmatic model, commands can be defined as beans of type `Command`:
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationBeanSnippets.java[tag=plain]
+----
+
+You can also use the `AbstractCommand` class to simplify command definitions:
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationBeanSnippets.java[tag=abstractcommand]
+----
+
+`AbstractCommand` provides some utility methods to simplify command creation like
+handling help options (`-h` and `--help`) and printing messages to the shell output.

spring-shell-docs/modules/ROOT/pages/commands/registration/annotation.adoc

@@ -1,5 +1,5 @@
 [[syntax]]
-= Command syntax
+= Command Syntax
 
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 

spring-shell-docs/modules/ROOT/pages/commands/registration/index.adoc

@@ -1,5 +1,5 @@
 [[writing]]
-= Writing
+= Writing Output
 
 ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs]