Doc fixes.

10 files changed, 88 insertions, 26 deletions

diff --git a/cpp/slice/Ice/Communicator.ice b/cpp/slice/Ice/Communicator.ice
index be22673d04b..058b7c4d227 100644
--- a/cpp/slice/Ice/Communicator.ice
+++ b/cpp/slice/Ice/Communicator.ice
@@ -102,9 +102,9 @@ local interface Communicator
 
     /**
      *
-     * Check whether communicator has been shutdown.
+     * Check whether communicator has been shut down.
      *
-     * @return Whether communicator has been shutdown.
+     * @return True if the communicator has been shut down; false otherwise.
      *
      * @see shutdown
      *
diff --git a/cpp/slice/Ice/LocalException.ice b/cpp/slice/Ice/LocalException.ice
index 649c42d4f81..e1ac62e5248 100644
--- a/cpp/slice/Ice/LocalException.ice
+++ b/cpp/slice/Ice/LocalException.ice
@@ -123,7 +123,7 @@ local exception NotRegisteredException
  * This exception is raised if an attempt is made to invoke an
  * operation with [ice_oneway], [ice_batchOneway], [ice_datagram],
  * or [ice_batchDatagram] and the operation has a return value,
- * out parameters, or an exception specification.
+ * out-parameters, or an exception specification.
  *
  **/
 local exception TwowayOnlyException
@@ -211,7 +211,7 @@ local exception UnknownUserException extends UnknownException
 /**
  *
  * This exception is raised if the Ice library version does not match
- * the Ice header files version.
+ * the version in the Ice header files.
  *
  **/
 local exception VersionMismatchException
@@ -865,7 +865,7 @@ local exception EncapsulationException extends MarshalException
 /**
  *
  * This exception is raised if a negative size
- * (e.g., a negative sequence size) is received.
+ * (for example, a negative sequence size) is received.
  *
  **/
 local exception NegativeSizeException extends MarshalException
diff --git a/cpp/slice/Ice/ObjectAdapter.ice b/cpp/slice/Ice/ObjectAdapter.ice
index 0976fb0aec3..2975c2f879c 100644
--- a/cpp/slice/Ice/ObjectAdapter.ice
+++ b/cpp/slice/Ice/ObjectAdapter.ice
@@ -75,7 +75,7 @@ local interface ObjectAdapter
      * <p class="Note"> Holding is not immediate, i.e., after [hold]
      * returns, the object adapter might still be active for some
      * time. You can use [waitForHold] to wait until holding is
-     * complete.</p>
+     * complete.
      *
      * @see activate
      * @see deactivate
@@ -113,7 +113,7 @@ local interface ObjectAdapter
      * been started before [deactivate] was called might still be
      * active. You can use [waitForDeactivate] to wait for the
      * completion of all requests for this object
-     * adapter.</p>
+     * adapter.
      *
      * @see activate
      * @see hold
@@ -145,7 +145,7 @@ local interface ObjectAdapter
      *
      * @return Whether adapter has been deactivated.
      *
-     * @see shutdown
+     * @see Communicator::shutdown
      *
      **/
     ["cpp:const"] bool isDeactivated();
@@ -327,7 +327,7 @@ local interface ObjectAdapter
      *
      * <p class="Note">This operation only tries to lookup a servant in
      * the Active Servant Map. It does not attempt to find a servant
-     * by using any installed [ServantLocator].</p>
+     * by using any installed [ServantLocator].
      *
      * @param id The identity of the Ice object for which the
      * servant should be returned.
@@ -390,7 +390,7 @@ local interface ObjectAdapter
      *
      * <p class="Note">This operation only tries to lookup a servant in
      * the Active Servant Map. It does not attempt to find a servant
-     * via any installed [ServantLocator]s.</p>
+     * via any installed [ServantLocator]s.
      *
      * @param proxy The proxy for which the servant should be returned.
      *
@@ -438,7 +438,7 @@ local interface ObjectAdapter
      * </ol>
      *
      * <p class="Note">Only one locator for the empty category can be
-     * installed.</p>
+     * installed.
      *
      * @param locator The locator to add.
      *
@@ -529,7 +529,7 @@ local interface ObjectAdapter
      *
      * <p class="Note"> This operation is intended to be used by special
      * services, such as [Router] implementations. Regular user code
-     * should not attempt to use this operation.</p>
+     * should not attempt to use this operation.
      *
      * @param id The identity for which a proxy is to be created.
      *
diff --git a/cpp/slice/Ice/Router.ice b/cpp/slice/Ice/Router.ice
index 12708ed72e1..67307800810 100644
--- a/cpp/slice/Ice/Router.ice
+++ b/cpp/slice/Ice/Router.ice
@@ -54,7 +54,7 @@ interface Router
      * @param proxy The proxy to add.
      *
      **/
-    ["deprecate:addProxy() has been deprecated, use addProxies() instead."]
+    ["deprecate:addProxy() is deprecated, use addProxies() instead."]
     idempotent void addProxy(Object* proxy);
 
     /**
diff --git a/cpp/slice/IceBox/IceBox.ice b/cpp/slice/IceBox/IceBox.ice
index 9786223a722..4f9b4236e99 100644
--- a/cpp/slice/IceBox/IceBox.ice
+++ b/cpp/slice/IceBox/IceBox.ice
@@ -28,8 +28,9 @@ module IceBox
     
 /**
  *
- * Indicates a failure occurred. For example, if a service encounters
- * an error during initialization, or if the service manager is unable
+ * This exception is a general failure notification. It is thrown
+ * for errors such as a service encountering an error during
+ * initialization, or the service manager being unable
  * to load a service executable.
  *
  **/
@@ -46,7 +47,8 @@ local exception FailureException
 
 /**
  *
- * Thrown is service is already started.
+ * This exception is thrown if an attempt is made to start an
+ * already-started service.
  *
  **/
 exception AlreadyStartedException
@@ -55,7 +57,8 @@ exception AlreadyStartedException
 
 /**
  *
- * Thrown is service is already stopped.
+ * This exception is thrown if an attempt is made to stop an
+ * already-stopped service.
  *
  **/
 exception AlreadyStoppedException
@@ -64,7 +67,8 @@ exception AlreadyStoppedException
 
 /**
  *
- * Thrown if service does not exist
+ * This exception is thrown if a service name does not refer
+ * to an existing service.
  *
  **/
 exception NoSuchServiceException
@@ -149,7 +153,7 @@ interface ServiceManager
 
     /**
      *
-     * Shutdown all services. This will cause [Service::stop] to be
+     * Shut down all services. This causes [Service::stop] to be
      * invoked on all configured services.
      *
      **/
diff --git a/cpp/slice/IceGrid/Admin.ice b/cpp/slice/IceGrid/Admin.ice
index fae0254d1a8..c328713e0ef 100644
--- a/cpp/slice/IceGrid/Admin.ice
+++ b/cpp/slice/IceGrid/Admin.ice
@@ -298,6 +298,12 @@ struct RegistryInfo
      **/
     string endpoints;
 };
+
+/**
+ *
+ * A sequence of [RegistryInfo] structures.
+ *
+ **/
 sequence<RegistryInfo> RegistryInfoSeq;
 
 /**
@@ -317,6 +323,11 @@ struct LoadInfo
     float avg15;
 };
 
+/**
+ *
+ * Information about an [IceGrid] application.
+ *
+ **/
 struct ApplicationInfo
 {
     /** Unique application identifier. */
@@ -340,8 +351,19 @@ struct ApplicationInfo
     /** The application descriptor */
     ApplicationDescriptor descriptor;
 };
+
+/**
+ *
+ * A sequence of [ApplicationInfo] structures.
+ *
+ **/
 ["java:type:{java.util.LinkedList}"] sequence<ApplicationInfo> ApplicationInfoSeq;
 
+/**
+ *
+ * Information about updates to an [IceGrid] application.
+ *
+ **/
 struct ApplicationUpdateInfo
 {
     /** The update time. */
@@ -357,7 +379,6 @@ struct ApplicationUpdateInfo
     ApplicationUpdateDescriptor descriptor;
 };
 
-
 /**
  *
  * The IceGrid administrative interface. </p>
@@ -1067,6 +1088,11 @@ interface Admin
     ["nonmutating", "cpp:const"] idempotent Ice::SliceChecksumDict getSliceChecksums();
 };
 
+/**
+ *
+ * This interface provides access to IceGrid log file contents.
+ *
+ **/
 interface FileIterator
 {
     /**
diff --git a/cpp/slice/IceGrid/Descriptor.ice b/cpp/slice/IceGrid/Descriptor.ice
index 8e335eb2f90..451d0d61aa8 100644
--- a/cpp/slice/IceGrid/Descriptor.ice
+++ b/cpp/slice/IceGrid/Descriptor.ice
@@ -30,7 +30,18 @@ dictionary<string, string> StringStringDict;
  **/
 struct PropertyDescriptor
 {
+    /**
+     *
+     * The name of the property.
+     *
+     **/
     string name;
+
+    /**
+     *
+     * The value of the property.
+     *
+     **/
     string value;
 };
 
@@ -892,7 +903,7 @@ struct NodeUpdateDescriptor
     /**
      *
      * The updated load factor of the node (or null if the load factor
-     * wasn't updated.)
+     * was not updated).
      *
      **/
     BoxedString loadFactor;
diff --git a/cpp/slice/IceGrid/Exception.ice b/cpp/slice/IceGrid/Exception.ice
index 3e959c89a76..4689e70ea99 100644
--- a/cpp/slice/IceGrid/Exception.ice
+++ b/cpp/slice/IceGrid/Exception.ice
@@ -107,6 +107,11 @@ exception AdapterNotExistException
  **/
 exception ObjectExistsException
 {
+    /**
+     *
+     * The identity of the object.
+     *
+     **/
     Ice::Identity id;
 };
 
@@ -117,6 +122,11 @@ exception ObjectExistsException
  **/
 exception ObjectNotRegisteredException
 {
+    /**
+     *
+     * The identity of the object.
+     *
+     **/
     Ice::Identity id;
 };
 
@@ -127,6 +137,11 @@ exception ObjectNotRegisteredException
  **/
 exception NodeNotExistException
 {
+    /**
+     *
+     * The node name.
+     *
+     **/
     string name;
 };
 
@@ -137,12 +152,17 @@ exception NodeNotExistException
  **/
 exception RegistryNotExistException
 {
+    /**
+     *
+     * The registry name.
+     *
+     **/
     string name;
 };
 
 /**
  *
- * An exception for deployment failure errors.
+ * An exception for deployment errors.
  *
  **/
 exception DeploymentException
diff --git a/cpp/slice/IceGrid/Observer.ice b/cpp/slice/IceGrid/Observer.ice
index 88bfb6ca1c2..dfa4fdba37b 100644
--- a/cpp/slice/IceGrid/Observer.ice
+++ b/cpp/slice/IceGrid/Observer.ice
@@ -356,7 +356,7 @@ interface RegistryObserver
 {
     /**
      *
-     * The <tt>registryInit</tt> operation is called after the registration of
+     * The <tt>registryInit</tt> operation is called after registration of
      * an observer to indicate the state of the registries.
      *
      * @param registries The current state of the registries.
diff --git a/cpp/slice/IceGrid/Session.ice b/cpp/slice/IceGrid/Session.ice
index f3d69efb221..bd840cc674f 100644
--- a/cpp/slice/IceGrid/Session.ice
+++ b/cpp/slice/IceGrid/Session.ice
@@ -65,15 +65,16 @@ interface Session extends Glacier2::Session
     /**
      *
      * Allocate an object with the given type. Depending on the
-     * allocation timeout, this operation might hang until an object
+     * allocation timeout, this operation can block until an object
      * becomes available or until the timeout is reached.
      *
      * @param type The type of the object.
      *
      * @return The proxy of the allocated object.
      *
-     * @throws Raised if no objects with the given type can be
-     * allocated.
+     * @throws ObjectNotRegisteredException Raised if no objects with the given type can be allocated.
+     *
+     * @throws AllocationException Raised if the object could not be allocated.
      *
      * @see setAllocationTimeout
      * @see releaseObject