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 7dd9358f..0bb54ef8 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
@@ -7,18 +7,20 @@ Having a default value for an option is somewhat related to
 may want to know if the user defined an option and change behavior
 based on a default value:
 
-====
-[source, java, indent=0]
+[source,java,indent=0,role="primary"]
+.Programmatic
 ----
-include::{snippets}/OptionSnippets.java[tag=option-registration-default]
+include::{snippets}/OptionSnippets.java[tag=option-default-programmatic]
 ----
-====
 
-The annotation model also supports defining default values:
+[source,java,indent=0,role="secondary"]
+.Annotation
+----
+include::{snippets}/OptionSnippets.java[tag=option-default-annotation]
+----
 
-====
-[source, java, indent=0]
+[source,java,indent=0,role="secondary"]
+.Legacy Annotation
 ----
-include::{snippets}/OptionSnippets.java[tag=option-with-annotation-default]
+include::{snippets}/OptionSnippets.java[tag=option-default-legacyannotation]
 ----
-====
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 89e8f495..e8bc088f 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
@@ -3,21 +3,44 @@
 ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
 
 An option is either required or not and, generally speaking, how it behaves depends on
-a command target:
+a command target.
 
-====
-[source, java, indent=0]
-----
-include::{snippets}/OptionSnippets.java[tag=option-registration-optional]
-----
-====
+Making option optional.
 
-In the annotation model, there is no direct way to define if argument is
-optional. Instead, it is instructed to be `NULL`:
+[source,java,indent=0,role="primary"]
+.Programmatic
+----
+include::{snippets}/OptionSnippets.java[tag=option-optional-programmatic]
+----
 
-====
-[source, java, indent=0]
+[source,java,indent=0,role="secondary"]
+.Annotation
 ----
-include::{snippets}/OptionSnippets.java[tag=option-with-annotation-optional]
+include::{snippets}/OptionSnippets.java[tag=option-optional-annotation]
+----
+
+[source,java,indent=0,role="secondary"]
+.Legacy Annotation
+----
+include::{snippets}/OptionSnippets.java[tag=option-optional-legacyannotation]
+----
+
+Making option mandatory.
+
+[source,java,indent=0,role="primary"]
+.Programmatic
+----
+include::{snippets}/OptionSnippets.java[tag=option-mandatory-programmatic]
+----
+
+[source,java,indent=0,role="secondary"]
+.Annotation
+----
+include::{snippets}/OptionSnippets.java[tag=option-mandatory-annotation]
+----
+
+[source,java,indent=0,role="secondary"]
+.Legacy Annotation
+----
+include::{snippets}/OptionSnippets.java[tag=option-mandatory-legacyannotation]
 ----
-====
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 3e49dce8..fe68caca 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
@@ -307,6 +307,28 @@ public class OptionSnippets {
 			return String.format("Hi '%s'", arg);
 		}
 		// end::option-registration-zerooronewithminmax-legacyannotation[]
+
+		// tag::option-optional-legacyannotation[]
+		void optionalOption(
+			@ShellOption(defaultValue = ShellOption.NULL) String arg
+		) {
+		}
+		// end::option-optional-legacyannotation[]
+
+		// tag::option-mandatory-legacyannotation[]
+		void mandatoryOption(
+			@ShellOption() String arg
+		) {
+		}
+		// end::option-mandatory-legacyannotation[]
+
+		// tag::option-default-legacyannotation[]
+		void defaultOption(
+			@ShellOption(defaultValue = "default") String arg
+		) {
+		}
+		// end::option-default-legacyannotation[]
+
 	}
 
 	static class Annotation {
@@ -329,6 +351,27 @@ public class OptionSnippets {
 		}
 		// end::option-registration-zerooronewithminmax-annotation[]
 
+		// tag::option-optional-annotation[]
+		void optionalOption(
+			@Option(required = false) String arg
+		) {
+		}
+		// end::option-optional-annotation[]
+
+		// tag::option-mandatory-annotation[]
+		void mandatoryOption(
+			@Option(required = true) String arg
+		) {
+		}
+		// end::option-mandatory-annotation[]
+
+		// tag::option-default-annotation[]
+		void defaultOption(
+			@Option(defaultValue = "default") String arg
+		) {
+		}
+		// end::option-default-annotation[]
+
 	}
 
 	static class Registration {
@@ -357,5 +400,41 @@ public class OptionSnippets {
 		}
 		// end::option-registration-zerooronewithminmax-programmatic[]
 
+		// tag::option-optional-programmatic[]
+		CommandRegistration optionalOption() {
+			return CommandRegistration.builder()
+				.command("optionalOption")
+				.withOption()
+					.longNames("arg")
+					.required(false)
+					.and()
+				.build();
+		}
+		// end::option-optional-programmatic[]
+
+		// tag::option-mandatory-programmatic[]
+		CommandRegistration mandatoryOption() {
+			return CommandRegistration.builder()
+				.command("optionalOption")
+				.withOption()
+					.longNames("arg")
+					.required()
+					.and()
+				.build();
+		}
+		// end::option-mandatory-programmatic[]
+
+		// tag::option-default-programmatic[]
+		CommandRegistration defaultOption() {
+			return CommandRegistration.builder()
+				.command("defaultOption")
+				.withOption()
+					.longNames("arg")
+					.defaultValue("default")
+					.and()
+				.build();
+		}
+		// end::option-default-programmatic[]
+
 	}
 }