Skip to content

Commit 755cf66

Browse files
committed
Update annotation docs
- Relates #637
1 parent 9d27466 commit 755cf66

File tree

3 files changed

+124
-20
lines changed

3 files changed

+124
-20
lines changed

spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,18 +7,20 @@ Having a default value for an option is somewhat related to
77
may want to know if the user defined an option and change behavior
88
based on a default value:
99

10-
====
11-
[source, java, indent=0]
10+
[source,java,indent=0,role="primary"]
11+
.Programmatic
1212
----
13-
include::{snippets}/OptionSnippets.java[tag=option-registration-default]
13+
include::{snippets}/OptionSnippets.java[tag=option-default-programmatic]
1414
----
15-
====
1615

17-
The annotation model also supports defining default values:
16+
[source,java,indent=0,role="secondary"]
17+
.Annotation
18+
----
19+
include::{snippets}/OptionSnippets.java[tag=option-default-annotation]
20+
----
1821

19-
====
20-
[source, java, indent=0]
22+
[source,java,indent=0,role="secondary"]
23+
.Legacy Annotation
2124
----
22-
include::{snippets}/OptionSnippets.java[tag=option-with-annotation-default]
25+
include::{snippets}/OptionSnippets.java[tag=option-default-legacyannotation]
2326
----
24-
====

spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,44 @@
33
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
44

55
An option is either required or not and, generally speaking, how it behaves depends on
6-
a command target:
6+
a command target.
77

8-
====
9-
[source, java, indent=0]
8+
Making option optional.
9+
10+
[source,java,indent=0,role="primary"]
11+
.Programmatic
12+
----
13+
include::{snippets}/OptionSnippets.java[tag=option-optional-programmatic]
14+
----
15+
16+
[source,java,indent=0,role="secondary"]
17+
.Annotation
18+
----
19+
include::{snippets}/OptionSnippets.java[tag=option-optional-annotation]
20+
----
21+
22+
[source,java,indent=0,role="secondary"]
23+
.Legacy Annotation
1024
----
11-
include::{snippets}/OptionSnippets.java[tag=option-registration-optional]
25+
include::{snippets}/OptionSnippets.java[tag=option-optional-legacyannotation]
1226
----
13-
====
1427

15-
In the annotation model, there is no direct way to define if argument is
16-
optional. Instead, it is instructed to be `NULL`:
28+
Making option mandatory.
29+
30+
[source,java,indent=0,role="primary"]
31+
.Programmatic
32+
----
33+
include::{snippets}/OptionSnippets.java[tag=option-mandatory-programmatic]
34+
----
35+
36+
[source,java,indent=0,role="secondary"]
37+
.Annotation
38+
----
39+
include::{snippets}/OptionSnippets.java[tag=option-mandatory-annotation]
40+
----
1741

18-
====
19-
[source, java, indent=0]
42+
[source,java,indent=0,role="secondary"]
43+
.Legacy Annotation
2044
----
21-
include::{snippets}/OptionSnippets.java[tag=option-with-annotation-optional]
45+
include::{snippets}/OptionSnippets.java[tag=option-mandatory-legacyannotation]
2246
----
23-
====

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

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -307,6 +307,28 @@ String zeroOrOneWithMinMax(
307307
return String.format("Hi '%s'", arg);
308308
}
309309
// end::option-registration-zerooronewithminmax-legacyannotation[]
310+
311+
// tag::option-optional-legacyannotation[]
312+
void optionalOption(
313+
@ShellOption(defaultValue = ShellOption.NULL) String arg
314+
) {
315+
}
316+
// end::option-optional-legacyannotation[]
317+
318+
// tag::option-mandatory-legacyannotation[]
319+
void mandatoryOption(
320+
@ShellOption() String arg
321+
) {
322+
}
323+
// end::option-mandatory-legacyannotation[]
324+
325+
// tag::option-default-legacyannotation[]
326+
void defaultOption(
327+
@ShellOption(defaultValue = "default") String arg
328+
) {
329+
}
330+
// end::option-default-legacyannotation[]
331+
310332
}
311333

312334
static class Annotation {
@@ -329,6 +351,27 @@ String zeroOrOneWithMinMax(
329351
}
330352
// end::option-registration-zerooronewithminmax-annotation[]
331353

354+
// tag::option-optional-annotation[]
355+
void optionalOption(
356+
@Option(required = false) String arg
357+
) {
358+
}
359+
// end::option-optional-annotation[]
360+
361+
// tag::option-mandatory-annotation[]
362+
void mandatoryOption(
363+
@Option(required = true) String arg
364+
) {
365+
}
366+
// end::option-mandatory-annotation[]
367+
368+
// tag::option-default-annotation[]
369+
void defaultOption(
370+
@Option(defaultValue = "default") String arg
371+
) {
372+
}
373+
// end::option-default-annotation[]
374+
332375
}
333376

334377
static class Registration {
@@ -357,5 +400,41 @@ CommandRegistration zeroOrOneWithMinMax() {
357400
}
358401
// end::option-registration-zerooronewithminmax-programmatic[]
359402

403+
// tag::option-optional-programmatic[]
404+
CommandRegistration optionalOption() {
405+
return CommandRegistration.builder()
406+
.command("optionalOption")
407+
.withOption()
408+
.longNames("arg")
409+
.required(false)
410+
.and()
411+
.build();
412+
}
413+
// end::option-optional-programmatic[]
414+
415+
// tag::option-mandatory-programmatic[]
416+
CommandRegistration mandatoryOption() {
417+
return CommandRegistration.builder()
418+
.command("optionalOption")
419+
.withOption()
420+
.longNames("arg")
421+
.required()
422+
.and()
423+
.build();
424+
}
425+
// end::option-mandatory-programmatic[]
426+
427+
// tag::option-default-programmatic[]
428+
CommandRegistration defaultOption() {
429+
return CommandRegistration.builder()
430+
.command("defaultOption")
431+
.withOption()
432+
.longNames("arg")
433+
.defaultValue("default")
434+
.and()
435+
.build();
436+
}
437+
// end::option-default-programmatic[]
438+
360439
}
361440
}

0 commit comments

Comments
 (0)