additional doco for dynamic method selection

Author: paulk-asert

src/spec/doc/core-object-orientation.adoc

@@ -529,6 +529,13 @@ a|
 ----
 include::{projectdir}/src/spec/test/objectorientation/MethodsTest.groovy[tags=multi_method_distance_interface_over_super,indent=0]
 ----
+
+| For a primitive argument type, a declared parameter type which is the same or slightly larger is preferred.
+a|
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/objectorientation/MethodsTest.groovy[tags=primitive_larger_over_smaller,indent=0]
+----
 |====
 
 In the case where two variants have exactly the same distance, this is deemed ambiguous and will cause a runtime exception:

src/spec/test/objectorientation/MethodsTest.groovy

@@ -240,6 +240,16 @@ class MethodsTest extends GroovyTestCase {
             // end::object_array_over_object[]
         '''
 
+        assertScript '''
+            // tag::primitive_larger_over_smaller[]
+            def method(Long l) { 'Long' }
+            def method(Short s) { 'Short' }
+            def method(BigInteger bi) { 'BigInteger' }
+
+            assert method(35) == 'Long'
+            // end::primitive_larger_over_smaller[]
+        '''
+
         assertScript '''
             // tag::multi_method_distance_interface_over_super[]
             interface I {}