[GR-19691] Update host interop docs

PullRequest: truffleruby/4073

Author: eregon

doc/user/jruby-migration.md

@@ -327,28 +327,31 @@ require 'java'
 # With the 'require' above, you now can refer to things that are part of the
 # standard Java platform via their full paths.
 frame = javax.swing.JFrame.new("Window") # Creating a Java JFrame
-label = javax.swing.JLabel.new("Hello")
+label = javax.swing.JLabel.new("Hello World")
 
 # You can transparently call Java methods on Java objects, just as if they were defined in Ruby.
 frame.add(label)  # Invoking the Java method 'add'.
-frame.setDefaultCloseOperation(javax.swing.JFrame::EXIT_ON_CLOSE)
+frame.setDefaultCloseOperation(javax.swing.WindowConstants::EXIT_ON_CLOSE)
 frame.pack
 frame.setVisible(true)
+sleep
 ```
 
 In TruffleRuby we would write that this way instead:
 
 ```ruby
 Java.import 'javax.swing.JFrame'
 Java.import 'javax.swing.JLabel'
+Java.import 'javax.swing.WindowConstants'
 
 frame = JFrame.new("Window")
-label = JLabel.new("Hello")
+label = JLabel.new("Hello World")
 
 frame.add(label)
-frame.setDefaultCloseOperation(JFrame[:EXIT_ON_CLOSE])
+frame.setDefaultCloseOperation(WindowConstants.EXIT_ON_CLOSE)
 frame.pack
 frame.setVisible(true)
+sleep
 ```
 
 Instead of using Ruby metaprogramming to simulate a Java package name, we explicitly import classes.
@@ -380,11 +383,31 @@ In both JRuby and TruffleRuby you call Java methods as you would a Ruby method.
 JRuby will rewrite method names such as `my_method` to the Java convention of `myMethod`, and convert `getFoo` to `foo`, and `setFoo` to `foo=`.
 TruffleRuby does not perform these conversions.
 
+### Calling Overloaded Method
+
+When multiple overloads are possible, it needs to be selected explicitly.
+For instance `java.util.concurrent.ExecutorService` has both `submit(Runnable)` and `submit(Callable<T> task)`.
+Calling submit without specifying which one shows the possible overloads:
+```
+$ ruby -e 'Java.type("java.util.concurrent.Executors").newFixedThreadPool(1).submit {}'
+-e:1:in `main': Multiple applicable overloads found for method name submit (candidates: [
+  Method[public java.util.concurrent.Future java.util.concurrent.AbstractExecutorService.submit(java.util.concurrent.Callable)],
+  Method[public java.util.concurrent.Future java.util.concurrent.AbstractExecutorService.submit(java.lang.Runnable)]],
+  arguments: [RubyProc@4893b344 (RubyProc)]) (TypeError)
+```
+
+You can select a specific overload using:
+```ruby
+executor = Java.type("java.util.concurrent.Executors").newFixedThreadPool(1)
+executor['submit(java.lang.Runnable)'].call(-> { 1 })
+# or
+executor.send("submit(java.lang.Runnable)") { 1 }
+```
+
 ### Referring to Constants
 
 In JRuby, Java constants are modelled as Ruby constants, `MyClass::FOO`.
-In TruffleRuby you use the read notation to read them as a property,
-`MyClass[:FOO]`.
+In TruffleRuby you use the read notation to read them as a property, `MyClass.FOO` or `MyClass[:FOO]`.
 
 ### Using Classes from JAR files
 

doc/user/polyglot.md

@@ -151,8 +151,7 @@ It is easier to use Java interoperability in JVM mode (`--jvm`). Java interopera
 See [here](https://github.com/oracle/graal/blob/master/docs/reference-manual/embedding/embed-languages.md#build-native-images-from-polyglot-applications) for more details.
 
 `Java.type('name')` returns a Java type, given a name such as `java.lang.Integer` or `int[]`.
-With the type object, `.new` will create an instance, `.foo` will call the static method `foo`, `[:FOO]` will read the static field
-`FOO`, and so on.
+With the type object, `.new` will create an instance, `.foo` will call the static method `foo`, `.FOO` or `[:FOO]` will read the static field `FOO`, and so on.
 To access methods of the `java.lang.Class` instance, use `[:class]`, such as `MyClass[:class].getName`.
 You can also go from the `java.lang.Class` instance to the Java type by using `[:static]`.