1409 documentation tests

docs/index.adoc

@@ -3138,6 +3138,60 @@ usage help shows the wrong default value
 ----
 ====
 
+==== Default Values in Unreferenced Argument Groups
+When an argument group is defined with default values in the annotated fields, but during usage does not reference any of the arguments within the group, picocli will instantiate those objects to their declared values.  However, picocli will instantiate the other objects to their default annotated values if a single argument within the argument group is defined.
+
+.Java
+[source,java,role="primary"]
+----
+@Command(name = "test", description = "demonstrates Default Value declaration")
+class MyApp {
+    @ArgGroup Outer outer;
+
+    class Outer {
+        @Options(names = "-x", defaultValue = "XX") String x;
+        @ArgGroup(exclusive = "true") Inner inner;
+    }
+
+    class Inner {
+        @Options(names = "-a", defaultValue = "AA") String a = "AA";
+        @Options(names = "-b", defaultValue = "BB") String b = "BB";
+    }
+
+    public void run() {
+        if (outer  ==  null) { // no options specified on command line; apply default values
+            outer = new Outer;
+        }
+        if (outer.inner  ==  null) { // handle nested sub-groups; apply default for inner group
+            outer.inner = new Inner;
+    }
+
+    // remaining business logic...
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Command(name = "test", description =["demonstrates Default Value declaration"])
+class MyApp {
+    @ArgGroup lateinit var outer: Outer
+
+    class Outer {
+        @Options(names = "-x", defaultValue = "XX") lateinit var x: String()
+        @ArgGroup lateinit var inner: Inner
+    }
+
+    class Inner {
+        @Options(names = "-a", defaultValue = "AA") var a = "AA"
+        @Options(names = "-b", defaultValue = "BB") var b = "BB"
+    }
+
+}
+----
+In this example above, there are two cases why we need to write our class with both annotated and declared values. The first reason is that if we do not supply any arguments, the annotated "defaultValues" field will provide the instantiated value. The second reason is if we provide an "x" value but no "a" or "b" value, the variables use their declared value instead of the annotated value. Thus, in our example, by setting the annotated "defaultValue" and the declared value to the same default value, we ensure that we always have the correct default value for different combinations of arguments.
+
+
 === Positional Parameters
 
 When a `@Parameters` positional parameter is part of a group, its `index` is the index _within the group_, not within the command.