diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc
index a5f0012b..1bdef6c7 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc
@@ -42,3 +42,12 @@ include::{snippets}/OptionSnippets.java[tag=option-registration-arityenum]
 |ONE_OR_MORE
 |1 / Integer MAX
 |===
+
+Annotation model only supports defining _max_ value of an arity.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/OptionSnippets.java[tag=option-with-annotation-arity]
+----
+====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc
index 8ae745cb..ee915877 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc
@@ -13,3 +13,12 @@ based on a default value.
 include::{snippets}/OptionSnippets.java[tag=option-registration-default]
 ----
 ====
+
+With an annotation model default value can be defined.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/OptionSnippets.java[tag=option-with-annotation-default]
+----
+====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc
index 32bbf79a..9413fb9a 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc
@@ -11,3 +11,13 @@ a command target how this behaves.
 include::{snippets}/OptionSnippets.java[tag=option-registration-optional]
 ----
 ====
+
+With an annotation model there is no direct way to define if argument is
+optional, instead it's instructed to be _NULL_.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/OptionSnippets.java[tag=option-with-annotation-optional]
+----
+====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc
index b6c24f67..0f0fb1c2 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc
+++ b/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc
@@ -25,3 +25,12 @@ as `-abc`, `-abc true` or `-abc false`.
 include::{snippets}/OptionSnippets.java[tag=option-registration-shortargbooleans]
 ----
 ====
+
+With annotation model you can define short argument directly.
+
+====
+[source, java, indent=0]
+----
+include::{snippets}/OptionSnippets.java[tag=option-with-annotation-shortarg]
+----
+====
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 1d4c516a..6ee31299 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
@@ -22,6 +22,46 @@ public class OptionSnippets {
 		// end::option-without-annotation[]
 	}
 
+	class Dump3 {
+		// tag::option-with-annotation-shortarg[]
+		public String example(
+			@ShellOption(value = { "-a" }) String arg1,
+			@ShellOption(value = { "-b" }) String arg2,
+			@ShellOption(value = { "-c" }) String arg3
+		) {
+			return "Hello " + arg1;
+		}
+		// end::option-with-annotation-shortarg[]
+	}
+
+	class Dump4 {
+		// tag::option-with-annotation-arity[]
+		public String example(@ShellOption(arity = 1) String arg1) {
+			return "Hello " + arg1;
+		}
+		// end::option-with-annotation-arity[]
+	}
+
+	class Dump5 {
+		// tag::option-with-annotation-optional[]
+		public String example(
+			@ShellOption(defaultValue = ShellOption.NULL) String arg1
+		) {
+			return "Hello " + arg1;
+		}
+		// end::option-with-annotation-optional[]
+	}
+
+	class Dump6 {
+		// tag::option-with-annotation-default[]
+		public String example(
+			@ShellOption(defaultValue = "defaultValue") String arg1
+		) {
+			return "Hello " + arg1;
+		}
+		// end::option-with-annotation-default[]
+	}
+
 	public void dump1() {
 
 		// tag::option-registration-longarg[]