improve explanation of var

src/spec/doc/core-semantics.adoc

@@ -39,22 +39,22 @@ This chapter covers the semantics of the Groovy programming language.
 
 === Variable definition
 
-Variables can be defined using either their type (like `String`) or by using the keyword `def` (or `var`) followed by a variable name:
+Variables can be defined using either their type (like `String`) or by using the keyword `def` followed by a variable name:
 
 [source,groovy]
 ----
-include::../test/SemanticsTest.groovy[tags=variable_definition_example,indent=0]
+include::../test/SemanticsTest.groovy[tags=variable_definition_example1,indent=0]
 ----
 
-`def` and `var` act as a type placeholder, i.e. a replacement for the type name,
+`def` acts as a type placeholder, i.e. a replacement for the type name,
 when you do not want to give an explicit type.
 It could be that you don't care about the type at compile time
 or are relying on type inference (with Groovy's static nature).
 It is mandatory for variable definitions to have a type or placeholder.
 If left out, the type name will be deemed to refer to an existing variable (presumably declared earlier).
 For scripts, undeclared variables are assumed to come from the Script binding.
 In other cases, you will get a missing property (dynamic Groovy) or compile time error (static Groovy).
-If you think of `def` and `var` as an alias of `Object`, you will understand in an instant.
+If you think of `def` as an alias of `Object`, you will understand in an instant.
 
 Variable definitions can provide an initial value,
 in which case it's like having a declaration and assignment (which we cover next) all in one.
@@ -63,6 +63,22 @@ in which case it's like having a declaration and assignment (which we cover next
 Variable definition types can be refined by using generics, like in `List<String> names`.
 To learn more about the generics support, please read the <<{core-object-orientation}#generics,generics section>>.
 
+[NOTE]
+--
+Java introduced the `var` reserved type from Java 10.
+It also acts like a type placeholder for variable definitions, similar to `def` above.
+So, for compatibility with Java,
+Groovy also lets you define variables using `var` as follows:
+[source,groovy]
+----
+include::../test/SemanticsTest.groovy[tags=variable_definition_example2,indent=0]
+----
+In the context of variable definitions, you can think of `var` as an alias for `def`.
+You might use `var` if you have cut-n-pasted some Java code into your codebase,
+or if the audience (readers or maintainers) of your codebase are primarily
+Java-aware folks, and you want to make the code look familiar to them.
+--
+
 === Variable assignment
 
 You can assign values to variables for later use. Try the following:

src/spec/test/SemanticsTest.groovy

@@ -22,11 +22,13 @@ import groovy.transform.Immutable
 class SemanticsTest extends CompilableTestSupport {
 
     void testVariableDefinition() {
-        // tag::variable_definition_example[]
+        // tag::variable_definition_example1[]
         String x
         def y
+        // end::variable_definition_example1[]
+        // tag::variable_definition_example2[]
         var z
-        // end::variable_definition_example[]
+        // end::variable_definition_example2[]
     }
 
     void testVariableAssignment() {