Document registration with @command

- Split and separate new annotations with legacy annotations
  on a registration level.
- Relates #637

Author: jvalkeal

spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-annotation.adoc

@@ -0,0 +1,52 @@
+[[commands-registration-annotation]]
+==== Annotation
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+`@Command` annotation when used on a method marks it 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]
+----
+====
+
+`@Command` annotation can be placed on a class which either defines defaults or shared settings
+for `@Command` methods defined in a same class. In below example a command `parent example` is
+defined.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/CommandAnnotationSnippets.java[tag=command-anno-in-class]
+----
+====
+
+Using a `@Command` will not automatically register command targets, instead it is required to use
+`@EnableCommand` and/or `@CommandScan` 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]
+----
+====
+
+You can define target classes using `@CommandScan`. It will get picked from all _Configuration_
+classes.
+
+TIP: Define `@CommandScan` in Spring Boot `App` class on a top level and it will automatically
+scan all command targets from all packages and classes under `App`.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/CommandAnnotationSnippets.java[tag=commandscan-no-args]
+----
+====

spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc

@@ -1,4 +1,5 @@
-==== Annotation Model
+[[commands-registration-legacyannotation]]
+==== Annotation Legacy
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 When you use the standard API, methods on beans are turned into executable commands, provided that:

spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc

@@ -1,5 +1,5 @@
-[[using-shell-commands-programmaticmodel]]
-==== Programmatic Model
+[[commands-registration-programmatic]]
+==== Programmatic
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 In the programmatic model, `CommandRegistration` can be defined as a `@Bean`

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

@@ -7,6 +7,15 @@ in a class and annotate the class and the methods with specific annotations.
 In the programmatic model, you use a more low level approach, defining command
 registrations (either as beans or by dynamically registering with a command catalog).
 
+Starting from _3.1.x_ a better support for defining commands using
+<<commands-registration-annotation, annotations>> were added. Firstly because eventually standard
+package providing <<commands-registration-legacyannotation, legacy annotations>> will get deprecated
+and removed. Secondly so that we're able to provide same set of features than using underlying
+`CommandRegistration`. Creating new a annotation model allows us to rethink and modernise that
+part without breaking existing applications.
+
+include::using-shell-commands-registration-annotation.adoc[]
+
 include::using-shell-commands-registration-legacyannotation.adoc[]
 
 include::using-shell-commands-registration-programmatic.adoc[]

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

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2023 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.shell.docs;
+
+import org.springframework.shell.command.annotation.Command;
+import org.springframework.shell.command.annotation.CommandScan;
+import org.springframework.shell.command.annotation.EnableCommand;
+
+class CommandAnnotationSnippets {
+
+		class Dump1 {
+
+			// tag::enablecommand-with-class[]
+			@EnableCommand(Example.class)
+			class App {
+			}
+			// end::enablecommand-with-class[]
+
+			// tag::command-anno-in-method[]
+			class Example {
+
+				@Command(command = "example")
+				public String example() {
+					return "Hello";
+				}
+			}
+			// end::command-anno-in-method[]
+		}
+
+		class Dump2 {
+
+			// tag::command-anno-in-class[]
+			@Command(command = "parent")
+			class Example {
+
+				@Command(command = "example")
+				public String example() {
+					return "Hello";
+				}
+			}
+			// end::command-anno-in-class[]
+		}
+
+		class Dump3 {
+
+			// tag::commandscan-no-args[]
+			@CommandScan
+			class App {
+			}
+			// end::commandscan-no-args[]
+		}
+
+}