diff options
Diffstat (limited to 'cpp')
| -rw-r--r-- | cpp/slice/Ice/Service.ice | 65 |
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. * **/ |