From 2f2da842d163acfa504878a7527ff1d59b3f93cc Mon Sep 17 00:00:00 2001
From: Martin Oberhuber < martin.oberhuber@windriver.com>
Date: Thu, 16 Nov 2006 10:13:23 +0000
Subject: [PATCH] Improve Javadoc in HostShellProcessAdapter

---
 .../shells/HostShellOutputStream.java         |  7 ++++-
 .../shells/HostShellProcessAdapter.java       | 28 +++++++++++++------
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/shells/HostShellOutputStream.java b/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/shells/HostShellOutputStream.java
index 167cebf669d..f0bc76658a1 100644
--- a/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/shells/HostShellOutputStream.java
+++ b/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/shells/HostShellOutputStream.java
@@ -8,6 +8,7 @@
  * Contributors: 
  * Ewa Matejska (PalmSource)
  * Martin Oberhuber (Wind River) - moved from org.eclipse.rse.remotecdt (bug 161777)
+ * Martin Oberhuber (Wind River) - improved Javadoc
  *******************************************************************************/
 
 package org.eclipse.rse.services.shells;
@@ -27,6 +28,7 @@ public class HostShellOutputStream extends OutputStream {
 	private IHostShell hostShell;
 	
 	/**
+	 * Constructor.
 	 * @param hostShell  An instance of the IHostShell class.  
 	 * The output will be sent to this instance.
 	 */
@@ -36,6 +38,7 @@ public class HostShellOutputStream extends OutputStream {
 	
 	/**
 	 * Writes one byte to the shell.
+	 * @see java.io.OutputStream#write(byte[])
 	 */
 	public void write(byte[] b) {
 		if(hostShell != null && b != null)
@@ -44,7 +47,8 @@ public class HostShellOutputStream extends OutputStream {
 	
     /**
      * Writes multiple bytes to the shell.
-     */
+	 * @see java.io.OutputStream#write(byte[], int, int)
+	 */
 	public void write(byte[] b, int off, int len)  {
 		if(hostShell != null && b != null)
 			hostShell.writeToShell(new String(b, off, len)); 
@@ -52,6 +56,7 @@ public class HostShellOutputStream extends OutputStream {
 
 	/**
 	 * Writes one character to the shell.
+	 * @see java.io.OutputStream#write(int)
 	 */
 	public void write(int b) throws IOException {
 		char[] array = { (char) b };
diff --git a/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/shells/HostShellProcessAdapter.java b/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/shells/HostShellProcessAdapter.java
index 0b7576f86a1..bc341226121 100644
--- a/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/shells/HostShellProcessAdapter.java
+++ b/rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/shells/HostShellProcessAdapter.java
@@ -10,6 +10,7 @@
  * Martin Oberhuber (Wind River) - adapt to IHostOutput API (bug 161773, 158312)
  * Martin Oberhuber (Wind River) - moved from org.eclipse.rse.remotecdt (bug 161777)
  * Martin Oberhuber (Wind River) - renamed from HostShellAdapter (bug 161777)
+ * Martin Oberhuber (Wind River) - improved Javadoc
  *******************************************************************************/
 
 package org.eclipse.rse.services.shells;
@@ -25,9 +26,9 @@ import java.io.PipedOutputStream;
  * This class represents a host shell process. It does not 
  * represent one process running in the shell.  This means 
  * that the output of multiple shell commands will be returned
- * until the shell exits. 
+ * until the shell exits.
+ * 
  * @author Ewa Matejska
- *
  */
 public class HostShellProcessAdapter extends Process implements
 IHostShellOutputListener {
@@ -41,7 +42,7 @@ IHostShellOutputListener {
 	private PipedOutputStream hostShellError = null;
 	
 	/**
-	 * 
+	 * Constructor.
 	 * @param hostShell  An instance of the IHostShell class.
 	 * @throws java.io.IOException
 	 */
@@ -57,7 +58,8 @@ IHostShellOutputListener {
 	}
 	
 	/**
-	 *  Exits the shell.
+	 * Exits the shell.
+	 * @see java.lang.Process#destroy()
 	 */
 	public synchronized void destroy() {
 		hostShell.exit();
@@ -69,13 +71,14 @@ IHostShellOutputListener {
 			errorStream.close();
 			outputStream.close();
 		} catch (IOException e) {
+			//FIXME IOException when closing one of the streams will leave others open
 			// Ignore
 		}	
 	}
 
 	/**
-	 *  There is no relevant exit value to return when the shell exits.
-	 *  This always returns 0.
+	 * There is no relevant exit value to return when the shell exits.
+	 * This always returns 0.
 	 */
 	public synchronized int exitValue() {
 		if(hostShell.isActive())
@@ -85,7 +88,8 @@ IHostShellOutputListener {
 	}
 
 	/**
-	 *  Returns the error stream of the shell.
+	 * Returns the error stream of the shell.
+	 * @see java.lang.Process#getErrorStream()
 	 */
 	public InputStream getErrorStream() {
 		return errorStream;
@@ -93,6 +97,7 @@ IHostShellOutputListener {
 
 	/**
 	 * Returns the input stream for the shell.
+	 * @see java.lang.Process#getInputStream()
 	 */
 	public InputStream getInputStream() {
 		return inputStream;
@@ -100,13 +105,15 @@ IHostShellOutputListener {
 
 	/**
 	 * Returns the output stream for the shell.
+	 * @see java.lang.Process#getOutputStream()
 	 */
 	public OutputStream getOutputStream() {
 		return outputStream;
 	}
 
 	/**
-	 *  Waits for the shell to exit.
+	 * Waits for the shell to exit.
+	 * @see java.lang.Process#waitFor()
 	 */
 	public synchronized int waitFor() throws InterruptedException {
 		
@@ -136,6 +143,11 @@ IHostShellOutputListener {
 		return 0;
 	}
 	
+	/**
+	 * Process an RSE Shell event, by writing the lines of text contained
+	 * in the event into the adapter's streams.
+	 * @see org.eclipse.rse.services.shells.IHostShellOutputListener#shellOutputChanged(org.eclipse.rse.services.shells.IHostShellChangeEvent)
+	 */
 	public void shellOutputChanged(IHostShellChangeEvent event) {
 		IHostOutput[] input = event.getLines();
 		OutputStream outputStream = event.isError() ? hostShellError : hostShellInput;