[Java] update api doc (#2988)

API doc is kind of out-dated, because of some recent code changes. Update it and add some simple examples.

java/doc/api.rst

@@ -7,29 +7,20 @@ Basic API
 ``Ray.init()``
 ~~~~~~~~~~~~~~
 
-``Ray.init`` should be invoked before any other Ray functions to initialize
-the runtime.
+``Ray.init`` is used to initialize Ray runtime. It should be called befored using
+any other Ray APIs.
 
 ``@RayRemote``
 ~~~~~~~~~~~~~~
 
 The ``@RayRemote`` annotation can be used to decorate static java
-methods and classes. The former indicates that a target function is a remote
-function, which is valid with the following requirements:
+methods and classes.
 
-- It must be a public static method.
-- The method must be deterministic for task reconstruction to behave correctly.
+When the annotation is used on a static method, the target method becomes
+a remote function.
 
-When the annotation is used for a class, the class becomes an actor class
-(an encapsulation of state shared among many remote functions). The
-member functions can be invoked using ``Ray.call``. The requirements for
-an actor class are as follows:
-
-- It must have a constructor without any parameters.
-- Any inner class must be public static.
-- It must not have any static fields or methods, as the semantic is undefined
-  with multiple instances of this same class on different machines.
-- All methods that will be invoked remotely must be ``public``.
+When the annotation is used on a class, the class becomes an actor class.
+An actor is the encapsulation of state shared among many remote functions.
 
 ``Ray.call``
 ~~~~~~~~~~~~
@@ -38,7 +29,7 @@ an actor class are as follows:
 
 .. code:: java
 
-    RayObject<R> call(Func func, ...);
+    RayObject<R> call(RayFunc func, ...);
 
 The parameters of ``Ray.call`` are the target method ``func``, followed by
 its original parameters.
@@ -50,6 +41,19 @@ its original parameters.
 The returned object is labeled as ``RayObject<R>`` and its value will be
 put into the object store on the machine where the function call is executed.
 
+Example:
+
+.. code:: java
+
+  public class Echo {
+
+    @RayRemote
+    public static String echo(String str) { return str; }
+
+  }
+
+  RayObject<String> res = Ray.call(Echo::echo, "hello");
+
 ``Ray.put``
 ~~~~~~~~~~~
 
@@ -58,34 +62,54 @@ store.
 
 .. code:: java
 
-    public static <T> RayObject<T> put(T object);
-    public static <T, TM> RayObject<T> put(T obj, TM metadata);
+  public static <T> RayObject<T> put(T object);
 
-``RayObject<T>.get/getMeta``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example:
 
 .. code:: java
 
-    public class RayObject<T> {
-        public T get() throws TaskExecutionException;
-        public <M> M getMeta() throws TaskExecutionException;
-    }
+  RayObject<String> fooObject = Ray.put("foo");
 
-These 2 methods will block the current thread until the requested data is
-locally available.
+``RayObject<T>.get``
+~~~~~~~~~~~~~~~~~~~~
+
+.. code:: java
+
+  public class RayObject<T> {
+    public T get();
+  }
+
+This method is used to fetch the value of this ``RayObject`` from the object store.
+It will block the current thread until the requested data is locally available.
+
+Example:
+
+.. code:: java
+
+  String foo = fooObject.get();
 
 ``Ray.wait``
 ~~~~~~~~~~~~
 
 ``Ray.wait`` is used to wait for a list of ``RayObject``\s to be locally available.
 It will block the current thread until ``numReturns`` objects are ready or
-``timeoutMilliseconds`` has passed.
+``timeoutMs`` has passed.
 
 .. code:: java
 
-    public static WaitResult<T> wait(List<RayObject<T>> waitfor, int numReturns, int timeoutMilliseconds);
-    public static WaitResult<T> wait(List<RayObject<T>> waitfor, int numReturns);
-    public static WaitResult<T> wait(List<RayObject<T>> waitfor);
+  public static WaitResult<T> wait(List<RayObject<T>> waitList, int numReturns, int timeoutMs);
+  public static WaitResult<T> wait(List<RayObject<T>> waitList, int numReturns);
+  public static WaitResult<T> wait(List<RayObject<T>> waitList);
+
+Example:
+
+.. code:: java
+
+  WaitResult<String> waitResult = Ray.wait(waitList, 5, 1000);
+  // `ready` is a list of objects that is already in local object store.
+  List<RayObject<String>> ready = waitResult.getReady();
+  // `unready` is the remaining objects that aren't in local object store.
+  List<RayObject<String>> unready = waitResult.getUnready();
 
 Actor Support
 -------------
@@ -97,30 +121,34 @@ A regular class annotated with ``@RayRemote`` is an actor class.
 
 .. code:: java
 
-    @RayRemote
-    public class Adder {
-      public Adder() {
-        sum = 0;
-      }
+  @RayRemote
+  public class Adder {
 
-      public int add(int n) {
-        return sum += n;
-      }
+    private int sum;
 
-      private int sum;
+    public Adder(int initValue) {
+      sum = initValue;
     }
 
-To create an actor instance, use ``Ray.create()``.
+    public int add(int n) {
+      return sum += n;
+    }
+  }
+
+To create an actor instance, use ``Ray.createActor()``.
 
 .. code:: java
 
-    RayActor<Adder> adder = Ray.create(Adder.class);
+    RayActor<Adder> adder = Ray.createActor(Adder::new, 0);
+
+Similar to ``Ray.call``, the first parameter of ``Ray.createActor`` is a method that returns an instance
+of the Actor class (the method can be either a constructor, or any factory methods). The rest of the parameters are
+the arguments of the method.
 
 Call Actor Methods
 ~~~~~~~~~~~~~~~~~~
 
-``Ray.call`` or its extended versions (e.g., ``Ray.call_n``)  are also
-used to call actor methods, and the actor instance must be the first parameter.
+``Ray.call`` is also used to call actor methods, where the actor instance must be the first parameter after the remote function.
 
 .. code:: java