fixing docu

1 files changed, 30 insertions, 35 deletions

diff --git a/cpp/slice/Ice/Service.ice b/cpp/slice/Ice/Service.ice
index 7f96647bc41..5905ab69d20 100644
--- a/cpp/slice/Ice/Service.ice
+++ b/cpp/slice/Ice/Service.ice
@@ -20,8 +20,7 @@ module Ice
     
 /**
  *
- * Used by a Service's [init] operation to indicate failure.
-// ML: [init] cannot be resolved. Use [Service::init].
+ * Used by a service to indicate failure.
  *
  **/
 local exception ServiceFailureException
@@ -30,30 +29,29 @@ local exception ServiceFailureException
 
 /**
  *
- * An application service. A Service is managed by a ServiceManager.
-// ML: Service Manager, or [ServiceManager]. (Please fix everywhere.)
- * A Service's lifecycle has three stages. The ServiceManager will
- * invoke [init] on all services prior to calling [start], and will
- * invoke [stop] on all services when [shutdown] is called. The order
- * in which the services are invoked is not defined.
+ * An application service managed by a [ServiceManager].
+ * The [ServiceManager] will invoke [init] on all services prior
+ * to calling [start], and will invoke [stop] on all services when
+ * [ServiceManager::shutdown] is called. The order in which the
+ * services are invoked is not defined. The service lifecycle
+ * operations are described below:
  *
- * <orderedlist>
+ * <itemizedlist>
  *
- * <listitem><para><important>init</important> - This is the
- * opportunity for the service to create a Communicator or Object
- * Adapter, register servants, etc.</para></listitem>
+ * <listitem><para>[init] - This is the opportunity for the service
+ * to create a Communicator or Object Adapter, register servants,
+ * etc.</para></listitem>
  *
- * <listitem><para><important>start</important> - Perform any
- * client-side activities which might result in an invocation
- * on a collocated service.</para></listitem>
+ * <listitem><para>[start] - Perform any client-side activities which
+ * might result in an invocation on a collocated service.
+ * </para></listitem>
  *
-// ML: start again? Should be shutdown, I guess.
- * <listitem><para><important>start</important> - Destroy
- * Communicators, deactivate Object Adapters, clean up resources,
- * etc.</para></listitem>
+ * <listitem><para>[stop] - Destroy Communicators, deactivate Object
+ * Adapters, clean up resources, etc. The [ServiceManager] guarantees
+ * that [stop] will be invoked on all services whose [init] has been
+ * invoked.</para></listitem>
  *
- * </orderedlist>
-// ML: Shouldn't a table be used here instead of a list? Or some other list type?
+ * </itemizedlist>
  *
  * <note><para>If the service requires an object adapter, it should
  * be created and activated in [init]. However, the service should
@@ -61,7 +59,7 @@ local exception ServiceFailureException
  * an invocation on a collocated service, because the order of
  * service configuration is not defined and therefore the target
  * service may not be active yet. Client-side activities can be
- * safely performed in [start], as the ServiceManager guarantees
+ * safely performed in [start], as the [ServiceManager] guarantees
  * that all services will be configured before [start] is invoked.
  * </para></note>
  *
@@ -72,19 +70,17 @@ local interface Service
 {
     /**
      *
-     * Initialize the Service. The <replaceable>communicator</replaceable>
-     // ML: Not replaceable, just literal, or use [].
-     * argument is the Communicator instance created by the ServiceManager.
-     * The service may use this instance, or may create its own as needed.
-     * The advantage of using this Communicator instance is that
-     * invocations between collocated services are optimized.
+     * Initialize the service. The given Communicator is created by the
+     * [ServiceManager]. The service may use this instance, or may
+     * create its own as needed. The advantage of using this Communicator
+     * instance is that invocations between collocated services are optimized.
      *
-     * <note><para>The ServiceManager owns this Communicator, and is
+     * <note><para>The [ServiceManager] owns this Communicator, and is
      * responsible for destroying it.</para></note>
      *
      * @param name The service's name, as determined by the configuration.
      *
-     * @param communicator The ServiceManager's Communicator instance.
+     * @param communicator The [ServiceManager]'s Communicator instance.
      *
      * @param properties The property set representing the service's
      * command-line arguments of the form
@@ -103,7 +99,7 @@ local interface Service
 
     /**
      *
-     * Start the Service.
+     * Start the service.
      *
      * @throws ServiceFailureException Raised if [start] failed.
      *
@@ -113,7 +109,7 @@ local interface Service
 
     /**
      *
-     * Stop the Service.
+     * Stop the service.
      *
      **/
     void stop();
@@ -121,8 +117,7 @@ local interface Service
 
 /**
  *
- * An application server.
-// ML: Application server? This expression is overused already...
+ * Administers a set of [Service] instances.
  *
  * @see Service
  *
@@ -131,7 +126,7 @@ interface ServiceManager
 {
     /**
      *
-     * Shutdown the server. This will cause [stop] to be invoked on
+     * Shutdown the server. This will cause [Service::stop] to be invoked on
      * all configured services.
      *
      **/