doc improvement.

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@1375 71c3de6d-444a-0410-be80-ed276b4c234a

remoting/src/main/java/hudson/remoting/Callable.java

@@ -5,6 +5,7 @@ import java.io.Serializable;
 /**
  * Represents computation to be done on a remote system.
  *
+ * @see Channel
  * @author Kohsuke Kawaguchi
  */
 public interface Callable<V,T extends Throwable> extends Serializable {

remoting/src/main/java/hudson/remoting/Channel.java

@@ -268,6 +268,9 @@ public class Channel {
      * Waits for this {@link Channel} to be closed down.
      *
      * The close-down of a {@link Channel} might be initiated locally or remotely.
+     *
+     * @throws InterruptedException
+     *      If the current thread is interrupted while waiting for the completion.
      */
     public synchronized void join() throws InterruptedException {
         while(!closed)

remoting/src/main/java/hudson/remoting/Pipe.java

@@ -22,9 +22,9 @@ import java.util.logging.Logger;
  * of pipes.
  *
  * <p>
- * Once created, {@link Pipe} can be sent to the remote system as a part of
- * {@link Callable} or any other object transportation mechanism between {@link Channel}s.
- * Once re-instanciated on the remote {@link Channel}, pipe connects
+ * Once created, {@link Pipe} can be sent to the remote system as a part of a serialization of
+ * {@link Callable} between {@link Channel}s.
+ * Once re-instanciated on the remote {@link Channel}, pipe automatically connects
  * back to the local instance and perform necessary set up.
  *
  * <p>
@@ -32,10 +32,24 @@ import java.util.logging.Logger;
  * read/write bytes.
  *
  * <p>
- * Pipe can be only written by one system and read by one system. It is an error to
+ * Pipe can be only written by one system and read by the other system. It is an error to
  * send one {@link Pipe} to two remote {@link Channel}s, or send one {@link Pipe} to
  * the same {@link Channel} twice.
  *
+ * <h2>Usage</h2>
+ * <pre>
+ * final Pipe p = Pipe.createLocalToRemote();
+ *
+ * channel.callAsync(new Callable() {
+ *   public Object call() {
+ *     InputStream in = p.getIn();
+ *     ... read from in ...
+ *   }
+ * });
+ *
+ * OutputStream out = p.getOut();
+ * ... write to out ...
+ * </pre>
  *
  * <h2>Implementation Note</h2>
  * <p>