From 8ddb883ead2e5270a68c580cfdb7e3bd7e260ad3 Mon Sep 17 00:00:00 2001
From: kohsuke <kohsuke@71c3de6d-444a-0410-be80-ed276b4c234a>
Date: Mon, 18 Dec 2006 17:59:06 +0000
Subject: [PATCH] doc improvement.

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@1375 71c3de6d-444a-0410-be80-ed276b4c234a
---
 .../main/java/hudson/remoting/Callable.java   |  1 +
 .../main/java/hudson/remoting/Channel.java    |  3 +++
 .../src/main/java/hudson/remoting/Pipe.java   | 22 +++++++++++++++----
 3 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/remoting/src/main/java/hudson/remoting/Callable.java b/remoting/src/main/java/hudson/remoting/Callable.java
index 2944829893..4bac2016cb 100644
--- a/remoting/src/main/java/hudson/remoting/Callable.java
+++ b/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 {
diff --git a/remoting/src/main/java/hudson/remoting/Channel.java b/remoting/src/main/java/hudson/remoting/Channel.java
index 4a77801355..0b4e9e4889 100644
--- a/remoting/src/main/java/hudson/remoting/Channel.java
+++ b/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)
diff --git a/remoting/src/main/java/hudson/remoting/Pipe.java b/remoting/src/main/java/hudson/remoting/Pipe.java
index 953a68da47..7adaaeaaa4 100644
--- a/remoting/src/main/java/hudson/remoting/Pipe.java
+++ b/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>
-- 
GitLab