2006-02-12 Wolfgang Baer <WBaer@gmx.de>

	* java/rmi/MarshalledObject.java: Added api docs to the class.
	* java/rmi/Remote.java: Added interface api docs.
	* java/rmi/package.html: Added package description.
	* java/rmi/AccessException.java: Minor api doc fixes.
	* java/rmi/NoSuchObjectException.java: Likewise.
	* java/rmi/AlreadyBoundException.java: Likewise.
	* java/rmi/RemoteException.java: Likewise.
	* java/rmi/NotBoundException.java: Likewise.
	* java/rmi/RMISecurityException.java: Likewise.
	* java/rmi/StubNotFoundException.java: Likewise.

10 files changed, 88 insertions, 29 deletions

diff --git a/java/rmi/AccessException.java b/java/rmi/AccessException.java
index b47078004..40954dfd3 100644
--- a/java/rmi/AccessException.java
+++ b/java/rmi/AccessException.java
@@ -1,5 +1,6 @@
 /* AccessException.java -- thrown if the caller does not have access
-   Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006 
+   Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -43,7 +44,7 @@ package java.rmi;
  *
  * @author unknown
  * @see Naming
- * @see ActivationSystem
+ * @see java.rmi.activation.ActivationSystem
  * @since 1.1
  */
 public class AccessException extends RemoteException
diff --git a/java/rmi/AlreadyBoundException.java b/java/rmi/AlreadyBoundException.java
index 091c0ee58..10f6e4cec 100644
--- a/java/rmi/AlreadyBoundException.java
+++ b/java/rmi/AlreadyBoundException.java
@@ -1,5 +1,6 @@
 /* AlreadyBoundException.java -- thrown if a binding is already bound
-   Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006 
+   Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -42,8 +43,8 @@ package java.rmi;
  * bound.
  *
  * @author unknown
- * @see Naming#bind(String, Remote)
- * @see Registry#bind(String, Remote)
+ * @see java.rmi.Naming#bind(String, Remote)
+ * @see java.rmi.registry.Registry#bind(String, Remote)
  * @since 1.1
  * @status updated to 1.4
  */
diff --git a/java/rmi/MarshalledObject.java b/java/rmi/MarshalledObject.java
index e07123804..e1a30f5f0 100644
--- a/java/rmi/MarshalledObject.java
+++ b/java/rmi/MarshalledObject.java
@@ -47,7 +47,16 @@ import java.io.IOException;
 import java.io.Serializable;
 
 /**
- * FIXME - doc missing
+ * A <code>MarshalledObject</code> consists of a serialized object which is
+ * marshalled according to the RMI specification.
+ * <p>
+ * An object passed to the constructor is serialized and tagged with the needed
+ * URL to retrieve its class definition for remote usage. If the object is a 
+ * remote reference its stub is serialized instead. The instance of this 
+ * marshalled object can be later retrieved by its <code>get()</code> method.
+ * </p>
+ *
+ * @author unknown
  */
 public final class MarshalledObject
   implements Serializable
@@ -59,7 +68,13 @@ public final class MarshalledObject
   byte[] locBytes;
   int hash;
 
-  public MarshalledObject(Object obj) throws java.io.IOException
+  /**
+   * Constructs a <code>MarshalledObject</code> from the given object.
+   * 
+   * @param obj the object to marshal
+   * @throws IOException if an I/O error during serialization occurs.
+   */
+  public MarshalledObject(Object obj) throws IOException
   {
     ByteArrayOutputStream objStream = new ByteArrayOutputStream();
     RMIMarshalledObjectOutputStream stream = 
@@ -79,6 +94,16 @@ public final class MarshalledObject
         hash = hash * 31 + locBytes[i];
   }
 
+  /**
+   * Checks if the given object is equal to this marshalled object.
+   * 
+   * <p>Marshalled objects are considered equal if they contain the
+   * same serialized object. Codebase annotations where the class 
+   * definition can be downloaded are ignored in the equals test.</p>
+   *
+   * @param obj the object to compare.   
+   * @return <code>true</code> if equal, <code>false</code> otherwise.
+   */
   public boolean equals(Object obj)
   {
     if (! (obj instanceof MarshalledObject))
@@ -102,6 +127,15 @@ public final class MarshalledObject
     return true;
   }
 
+  /**
+   * Constructs and returns a copy of the internal serialized object.
+   * 
+   * @return The deserialized object.
+   * 
+   * @throws IOException if an I/O exception occurs during deserialization.
+   * @throws ClassNotFoundException if the class of the deserialized object 
+   * cannot be found.
+   */
   public Object get() throws IOException, ClassNotFoundException
   {
     if (objBytes == null)
diff --git a/java/rmi/NoSuchObjectException.java b/java/rmi/NoSuchObjectException.java
index 69f7d6c52..294390670 100644
--- a/java/rmi/NoSuchObjectException.java
+++ b/java/rmi/NoSuchObjectException.java
@@ -1,5 +1,6 @@
 /* NoSuchObjectException.java -- thrown if the remote object no longer exists
-   Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006 
+   Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -43,9 +44,9 @@ package java.rmi;
  * obey the semantics of "at most once".
  *
  * @author unknown
- * @see RemoteObject#toStub(Remote)
- * @see UnicastRemoteObject#unexportObject(Remote, boolean)
- * @see Activatable#unexportObject(Remote, boolean)
+ * @see java.rmi.server.RemoteObject#toStub(Remote)
+ * @see java.rmi.server.UnicastRemoteObject#unexportObject(Remote, boolean)
+ * @see java.rmi.activation.Activatable#unexportObject(Remote, boolean)
  * @since 1.1
  * @status updated to 1.4
  */
diff --git a/java/rmi/NotBoundException.java b/java/rmi/NotBoundException.java
index b8bc0a532..03d4adf8f 100644
--- a/java/rmi/NotBoundException.java
+++ b/java/rmi/NotBoundException.java
@@ -1,5 +1,6 @@
 /* NotBoundException.java -- attempt to use a registry name with no binding
-   Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006 
+   Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -42,10 +43,10 @@ package java.rmi;
  * associated binding.
  *
  * @author unknown
- * @see Naming#lookup(String)
- * @see Naming#unbind(String)
- * @see Registry#lookup(String)
- * @see Registry#unbind(String)
+ * @see java.rmi.Naming#lookup(String)
+ * @see java.rmi.Naming#unbind(String)
+ * @see java.rmi.registry.Registry#lookup(String)
+ * @see java.rmi.registry.Registry#unbind(String)
  * @since 1.1
  * @status updated to 1.4
  */
diff --git a/java/rmi/RMISecurityException.java b/java/rmi/RMISecurityException.java
index a44a67e2a..6f15af852 100644
--- a/java/rmi/RMISecurityException.java
+++ b/java/rmi/RMISecurityException.java
@@ -1,5 +1,6 @@
 /* RMISecurityException.java -- deprecated version of SecurityException
-   Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006 
+   Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,11 +39,12 @@ exception statement from your version. */
 package java.rmi;
 
 /**
- * Never thrown, but originally intended to wrap a java.lang.SecurityException.
+ * Never thrown, but originally intended to wrap a 
+ * {@link java.lang.SecurityException} in the case of RMI.
  *
  * @author unknown
  * @since 1.1
- * @deprecated use {@link SecurityException} instead
+ * @deprecated use {@link java.lang.SecurityException} instead
  * @status updated to 1.4
  */
 public class RMISecurityException extends SecurityException
@@ -55,7 +57,7 @@ public class RMISecurityException extends SecurityException
   /**
    * Create an exception with a message.
    *
-   * @param s the message
+   * @param n the message
    * @deprecated no longer needed
    */
   public RMISecurityException(String n)
@@ -66,8 +68,8 @@ public class RMISecurityException extends SecurityException
   /**
    * Create an exception with a message and a cause.
    *
-   * @param s the message
-   * @param e the cause
+   * @param n the message
+   * @param a the cause (ignored)
    * @deprecated no longer needed
    */
   public RMISecurityException(String n, String a)
diff --git a/java/rmi/Remote.java b/java/rmi/Remote.java
index 93c8d0aa1..0306981e9 100644
--- a/java/rmi/Remote.java
+++ b/java/rmi/Remote.java
@@ -1,5 +1,5 @@
 /* Remote.java
-   Copyright (c) 1996, 1997, 1998, 1999 Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2006 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -37,5 +37,22 @@ exception statement from your version. */
 
 package java.rmi;
 
+/**
+ * Marker interface for interfaces which methods are invokable
+ * from outside of this virtual machine through remote method calls.
+ * <p>
+ * Remote invokable methods of remote object implementations are specified
+ * as the methods defined in the implemented remote interfaces. Typically 
+ * remote object implementations are subclasses of the convenience classes 
+ * {@link java.rmi.server.UnicastRemoteObject} or 
+ * {@link java.rmi.activation.Activatable} implementing one or more remote
+ * interfaces indicating their remotely accessible methods. The convenience
+ * classes provide implementations for correct remote object creation, 
+ * hash, equals and toString methods.
+ * </p>
+ * 
+ * @author unknown
+ */
 public interface Remote {
+  // marker interface
 }
diff --git a/java/rmi/RemoteException.java b/java/rmi/RemoteException.java
index cbbb26299..929bc80f6 100644
--- a/java/rmi/RemoteException.java
+++ b/java/rmi/RemoteException.java
@@ -1,5 +1,6 @@
 /* RemoteException.java -- common superclass for exceptions in java.rmi
-   Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006 
+   Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -86,7 +87,7 @@ public class RemoteException extends IOException
    * Create an exception with the given message and cause.
    *
    * @param s the message
-   * @param ex the cause
+   * @param e the cause
    */
   public RemoteException(String s, Throwable e)
   {
diff --git a/java/rmi/StubNotFoundException.java b/java/rmi/StubNotFoundException.java
index 2f9e0f5ff..524b418ce 100644
--- a/java/rmi/StubNotFoundException.java
+++ b/java/rmi/StubNotFoundException.java
@@ -1,5 +1,6 @@
 /* StubNotFoundException.java -- thrown if a valid stub is not found
-   Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006 
+   Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -41,8 +42,8 @@ package java.rmi;
  * Thrown if a valid stub class is not found for an object when it is exported.
  *
  * @author unknown
- * @see UnicastRemoteObject
- * @see Activatable
+ * @see java.rmi.server.UnicastRemoteObject
+ * @see java.rmi.activation.Activatable
  * @since 1.1
  * @status updated to 1.4
  */
diff --git a/java/rmi/package.html b/java/rmi/package.html
index a7bf85020..1d36fe80a 100644
--- a/java/rmi/package.html
+++ b/java/rmi/package.html
@@ -40,7 +40,7 @@ exception statement from your version. -->
 <head><title>GNU Classpath - java.rmi</title></head>
 
 <body>
-<p></p>
+<p>Provides basic Remote Method Invocation (RMI) interfaces, classes and exceptions.</p>
 
 </body>
 </html>