Fix alias handling with @Command annotation

- Revisit how alias commands are added using
  @Command annotation when using if/or on class
  and/or method level.
- With this change alias handling is more logical
  and there's better tests and docs.
- Backport #945
- Fixes #973

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

@@ -13,6 +13,7 @@
 *** xref:commands/exceptionhandling/resolving.adoc[]
 *** xref:commands/exceptionhandling/mappings.adoc[]
 *** xref:commands/exceptionhandling/annotation.adoc[]
+** xref:commands/alias.adoc[]
 ** xref:commands/hidden.adoc[]
 ** xref:commands/helpoptions.adoc[]
 ** xref:commands/interactionmode.adoc[]

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

@@ -0,0 +1,71 @@
+[[commands-alias]]
+= Alias
+
+ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs]
+
+It is possible to define an _alias_ for a command. This is convenient for
+cases where you want to create a shorter version of a command or going
+through a complete command rename while keeping old one temporarily in
+place.
+
+Format for _alias_ is slighly different than a _command_. When _command_
+is defined as an array it's concatenated together into a single command.
+When _alias_ is defined as an array it's used to create a separate
+aliases.
+
+Aliases with a plain `CommandRegistration` is simple and clear as you
+get exactly what you define as there's no "magic" in it.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=builder]
+----
+
+Defining alias with `@Command` annotation is a bit more involved as it
+can exist on a both class and method levels. Here are examples how it
+works.
+
+Alias just on a method gives you _myalias_.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=command1]
+----
+
+Or _myalias1_ and _myalias2_ if defined as an array.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=command2]
+----
+
+Alias only on a class level does nothing as it's simply an instruction
+for annotation on a *method level if defined*.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=command3]
+----
+
+Alias on both class and method level combines those two together where
+class level works as an prefix and method level as combination of aliases.
+Alias on a class level is usually used together with a _command_ prefix
+to keep aliases on a same command level.
+
+Here you'd get alias _myalias1 myalias2_.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=command4]
+----
+
+On a method level there's a special format, that being an *empty string*
+which allows you to create an alias but it only uses prefix from a
+class level.
+
+Here you'd get alias _myalias1_.
+
+[source, java, indent=0]
+----
+include::{snippets}/CommandRegistrationAliasSnippets.java[tag=command5]
+----

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

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2024 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.CommandRegistration;
+import org.springframework.shell.command.annotation.Command;
+
+class CommandRegistrationAliasSnippets {
+
+	// tag::builder[]
+	CommandRegistration commandRegistration() {
+		return CommandRegistration.builder()
+			.command("mycommand")
+			// define alias as myalias
+			.withAlias()
+				.command("myalias")
+				.and()
+			// define alias as myalias1 and myalias2
+			.withAlias()
+				.command("myalias1", "myalias2")
+				.and()
+			.build();
+	}
+	// end::builder[]
+
+	class Dump1 {
+
+		// tag::command1[]
+		@Command
+		class MyCommands {
+
+			@Command(command = "mycommand", alias = "myalias")
+			void myCommand() {
+			}
+		}
+		// end::command1[]
+	}
+
+	class Dump2 {
+
+		// tag::command2[]
+		@Command
+		class MyCommands {
+
+			@Command(command = "mycommand", alias = { "myalias1", "myalias2" })
+			void myCommand() {
+			}
+		}
+		// end::command2[]
+	}
+
+	class Dump3 {
+
+		// tag::command3[]
+		@Command(alias = "myalias")
+		class MyCommands {
+
+			@Command(command = "mycommand")
+			void myCommand() {
+			}
+		}
+		// end::command3[]
+	}
+
+	class Dump4 {
+
+		// tag::command4[]
+		@Command(alias = "myalias1")
+		class MyCommands {
+
+			@Command(command = "mycommand", alias = "myalias2")
+			void myCommand() {
+			}
+		}
+		// end::command4[]
+	}
+
+	class Dump5 {
+
+		// tag::command5[]
+		@Command(command = "mycommand", alias = "myalias")
+		class MyCommands {
+
+			@Command(command = "", alias = "")
+			void myMainCommand() {
+			}
+
+			@Command(command = "mysubcommand", alias = "mysubalias")
+			void mySubCommand() {
+			}
+		}
+		// end::command5[]
+	}
+}