ICE-7167 - javadoc fixes

8 files changed, 36 insertions, 27 deletions

diff --git a/csharp/src/Glacier2/SessionHelper.cs b/csharp/src/Glacier2/SessionHelper.cs
index ea2cbb081dc..ae050e64b85 100644
--- a/csharp/src/Glacier2/SessionHelper.cs
+++ b/csharp/src/Glacier2/SessionHelper.cs
@@ -132,12 +132,10 @@ public class SessionHelper
     }
 
     /// <summary>
-    /// Returns the Glacier2 session proxy. If the session hasn't been
-    /// established yet, or the session has already been destroyed,
-    /// throws SessionNotExistException.
+    /// Returns the Glacier2 session proxy, or null if the session hasn't been
+    /// established yet or the session has already been destroyed.
     /// </summary>
-    /// <returns>The session proxy, or throws SessionNotExistException
-    /// if no session exists.</returns>
+    /// <returns>The session proxy, or null if no session exists.</returns>
     public Glacier2.SessionPrx
     session()
     {
diff --git a/java/src/Glacier2/src/main/java/com/zeroc/Glacier2/SessionHelper.java b/java/src/Glacier2/src/main/java/com/zeroc/Glacier2/SessionHelper.java
index 677d02af683..71c2c408827 100644
--- a/java/src/Glacier2/src/main/java/com/zeroc/Glacier2/SessionHelper.java
+++ b/java/src/Glacier2/src/main/java/com/zeroc/Glacier2/SessionHelper.java
@@ -119,10 +119,9 @@ public class SessionHelper
     }
 
     /**
-     * Returns the Glacier2 session proxy. If the session hasn't been established yet,
-     * or the session has already been destroyed, throws SessionNotExistException.
-     * @return The session proxy, or throws SessionNotExistException if no session exists.
-     * @throws SessionNotExistException No session exists.
+     * Returns the Glacier2 session proxy, or null if the session hasn't been established yet
+     * or the session has already been destroyed.
+     * @return The session proxy, or null if no session exists.
      */
     synchronized public SessionPrx session()
     {
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java b/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java
index 52ce5cb6544..d40e2d43221 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java
@@ -1043,6 +1043,8 @@ public class InputStream
     /**
      * Extracts a serializable Java object from the stream.
      *
+     * @param <T> The serializable type.
+     * @param cl The class for the serializable type.
      * @return The deserialized Java object.
      **/
     public <T extends java.io.Serializable> T readSerializable(Class<T> cl)
@@ -1086,7 +1088,9 @@ public class InputStream
     /**
      * Extracts a optional serializable Java object from the stream.
      *
+     * @param <T> The serializable type.
      * @param tag The numeric tag associated with the value.
+     * @param cl The class for the serializable type.
      * @return The optional value (if any).
      **/
     public <T extends java.io.Serializable> java.util.Optional<T> readSerializable(int tag, Class<T> cl)
@@ -1852,6 +1856,7 @@ public class InputStream
     /**
      * Extracts an optional proxy from the stream. The stream must have been initialized with a communicator.
      *
+     * @param <T> The proxy type.
      * @param tag The numeric tag associated with the value.
      * @param cast The uncheckedCast function to call on the unmarshaled proxy to obtain the correct proxy type.
      * @return The optional value (if any).
@@ -1901,6 +1906,8 @@ public class InputStream
     /**
      * Extracts a Slice value from the stream.
      *
+     * @param <T> The value type.
+     *
      * @param cb The consumer to notify when the extracted instance is available. The stream
      * extracts Slice values in stages. The Ice run time calls accept on the consumer when
      * the corresponding instance has been fully unmarshaled.
@@ -1944,6 +1951,8 @@ public class InputStream
     /**
      * Extracts an optional Slice value from the stream.
      *
+     * @param <T> The value type.
+     *
      * @param tag The numeric tag associated with the value.
      *
      * @param cb The consumer to notify when the extracted instance is available. The stream
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/OutputStream.java b/java/src/Ice/src/main/java/com/zeroc/Ice/OutputStream.java
index 384077d9a03..f0f5f6285ee 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/OutputStream.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/OutputStream.java
@@ -740,6 +740,7 @@ public class OutputStream
     /**
      * Writes an optional serializable Java object to the stream.
      *
+     * @param <T> The serializable class.
      * @param tag The optional tag.
      * @param v The optional serializable object to write.
      **/
diff --git a/slice/Ice/Communicator.ice b/slice/Ice/Communicator.ice
index 02c892940ae..a9037733c66 100644
--- a/slice/Ice/Communicator.ice
+++ b/slice/Ice/Communicator.ice
@@ -86,7 +86,7 @@ local interface Communicator
 
     /**
      *
-     * Shuts down this communicator's server functionality, which
+     * <p>Shuts down this communicator's server functionality, which
      * includes the deactivation of all object adapters. (Attempts to use
      * a deactivated object adapter raise {@link ObjectAdapterDeactivatedException}.)
      * Subsequent calls to {@link #shutdown} are ignored.</p>
@@ -235,7 +235,7 @@ local interface Communicator
 
     /**
      *
-     * Create a new object adapter. The endpoints for the object
+     * <p>Create a new object adapter. The endpoints for the object
      * adapter are taken from the property <tt><em>name</em>.Endpoints</tt>.</p>
      *
      * <p>It is legal to create an object adapter with the empty string as
@@ -259,7 +259,7 @@ local interface Communicator
 
     /**
      *
-     * Create a new object adapter with endpoints. This operation sets
+     * <p>Create a new object adapter with endpoints. This operation sets
      * the property <tt><em>name</em>.Endpoints</tt>,
      * and then calls {@link #createObjectAdapter}. It is provided as a
      * convenience function.</p>
@@ -282,7 +282,7 @@ local interface Communicator
 
     /**
      *
-     * Create a new object adapter with a router. This operation
+     * <p>Create a new object adapter with a router. This operation
      * creates a routed object adapter.</p>
      *
      * <p>Calling this operation with an empty name will result in a
@@ -427,7 +427,7 @@ local interface Communicator
 
     /**
      *
-     * Set a default router for this communicator. All newly
+     * <p>Set a default router for this communicator. All newly
      * created proxies will use this default router. To disable the
      * default router, null can be used. Note that this
      * operation has no effect on existing proxies.</p>
@@ -458,7 +458,7 @@ local interface Communicator
 
     /**
      *
-     * Set a default Ice locator for this communicator. All newly
+     * <p>Set a default Ice locator for this communicator. All newly
      * created proxy and object adapters will use this default
      * locator. To disable the default locator, null can be used.
      * Note that this operation has no effect on existing proxies or
@@ -609,22 +609,24 @@ local interface Communicator
 local enum ToStringMode
 {
     /**
-     * Characters > 127 are kept as-is in the resulting string. Non-printable ASCII
-     * characters <= 127 are encoded as \\t, \\n (etc.) or \\unnnn.
+     * Characters with ordinal values greater than 127 are kept as-is in the resulting string.
+     * Non-printable ASCII characters with ordinal values 127 and below are encoded as \\t, \\n (etc.)
+     * or \\unnnn.
      **/
     Unicode,
 
     /**
-     * Characters > 127 are encoded as universal character names in the resulting string:
-     * \\unnnn for BMP characters and \\Unnnnnnnn for non-BMP characters. Non-printable ASCII
-     * characters <= 127 are encoded as \\t, \\n (etc.) or \\unnnn.
+     * Characters with ordinal values greater than 127 are encoded as universal character names in
+     * the resulting string: \\unnnn for BMP characters and \\Unnnnnnnn for non-BMP characters.
+     * Non-printable ASCII characters with ordinal values 127 and below are encoded as \\t, \\n (etc.)
+     * or \\unnnn.
      **/
     ASCII,
 
     /**
-     * Characters > 127 are encoded as a sequence of UTF-8 bytes using octal escapes.
-     * characters <= 127 are encoded as \\t, \\n (etc.) or an octal escape. Use this mode
-     * to generate strings compatible with Ice 3.6 and earlier.
+     * Characters with ordinal values greater than 127 are encoded as a sequence of UTF-8 bytes using
+     * octal escapes. Characters with ordinal values 127 and below are encoded as \\t, \\n (etc.) or
+     * an octal escape. Use this mode to generate strings compatible with Ice 3.6 and earlier.
      **/
     Compat
 }
diff --git a/slice/Ice/ImplicitContext.ice b/slice/Ice/ImplicitContext.ice
index 2dabdda5e11..61fedcfe255 100644
--- a/slice/Ice/ImplicitContext.ice
+++ b/slice/Ice/ImplicitContext.ice
@@ -26,9 +26,10 @@ module Ice
  *
  * An interface to associate implict contexts with communicators.
  *
- * When you make a remote invocation without an explicit context parameter,
+ * <p>When you make a remote invocation without an explicit context parameter,
  * Ice uses the per-proxy context (if any) combined with the <tt>ImplicitContext</tt>
  * associated with the communicator.</p>
+ *
  * <p>Ice provides several implementations of <tt>ImplicitContext</tt>. The implementation
  * used depends on the value of the <tt>Ice.ImplicitContext</tt> property.
  * <dl>
@@ -46,7 +47,6 @@ module Ice
  * with <tt>java.lang.Object</tt> replaced by <tt>string</tt> and null replaced by the empty-string.
  *
  **/
-
 local interface ImplicitContext
 {
     /**
diff --git a/slice/Ice/Router.ice b/slice/Ice/Router.ice
index 4abf973ae0a..f9cd4b0bc18 100644
--- a/slice/Ice/Router.ice
+++ b/slice/Ice/Router.ice
@@ -40,7 +40,7 @@ interface Router
      *
      * @param hasRoutingTable Indicates whether or not the router supports a routing
      * table. If it is supported, the Ice runtime will call addProxies to populate the
-     * routing table. This out parameter is only supported starting with Ice >= 3.7.
+     * routing table. This out parameter is only supported starting with Ice 3.7.
      * The Ice runtime assumes the router has a routing table if the optional is not
      * set.
      *
diff --git a/slice/IceGrid/Admin.ice b/slice/IceGrid/Admin.ice
index cb94873e479..854182009c5 100644
--- a/slice/IceGrid/Admin.ice
+++ b/slice/IceGrid/Admin.ice
@@ -386,7 +386,7 @@ struct ApplicationUpdateInfo
 
 /**
  *
- * The IceGrid administrative interface. </p>
+ * The IceGrid administrative interface.
  * <p class="Warning">Allowing access to this interface
  * is a security risk! Please see the IceGrid documentation
  * for further information.