diff options
| -rw-r--r-- | cpp/doc/Makefile | 3 | ||||
| -rw-r--r-- | cpp/slice/Freeze/Evictor.ice | 15 | ||||
| -rw-r--r-- | cpp/slice/Freeze/EvictorStorage.ice | 2 | ||||
| -rw-r--r-- | cpp/slice/Glacier2/Router.ice | 2 | ||||
| -rw-r--r-- | cpp/slice/Ice/Current.ice | 9 | ||||
| -rw-r--r-- | cpp/slice/Ice/ImplicitContext.ice | 4 | ||||
| -rw-r--r-- | cpp/slice/Ice/LocalException.ice | 124 | ||||
| -rw-r--r-- | cpp/slice/Ice/ObjectAdapter.ice | 9 | ||||
| -rw-r--r-- | cpp/slice/Ice/Properties.ice | 3 | ||||
| -rw-r--r-- | cpp/slice/Ice/Router.ice | 2 | ||||
| -rw-r--r-- | cpp/slice/Ice/ServantLocator.ice | 4 | ||||
| -rw-r--r-- | cpp/slice/IceGrid/Admin.ice | 12 | ||||
| -rw-r--r-- | cpp/slice/IceGrid/Exception.ice | 86 | ||||
| -rwxr-xr-x | cpp/slice/IceGrid/FileParser.ice | 6 | ||||
| -rw-r--r-- | cpp/slice/IceGrid/Locator.ice | 7 | ||||
| -rw-r--r-- | cpp/slice/IceGrid/Observer.ice | 61 | ||||
| -rw-r--r-- | cpp/slice/IceGrid/Registry.ice | 5 | ||||
| -rw-r--r-- | cpp/slice/IceGrid/UserAccountMapper.ice | 2 | ||||
| -rw-r--r-- | cpp/slice/IcePatch2/FileServer.ice | 11 | ||||
| -rw-r--r-- | cpp/slice/IceStorm/IceStorm.ice | 16 | ||||
| -rw-r--r-- | cpp/src/slice2html/Gen.cpp | 46 | ||||
| -rw-r--r-- | cpp/src/slice2html/Gen.h | 10 | ||||
| -rw-r--r-- | cpp/src/slice2html/Main.cpp | 18 |
23 files changed, 278 insertions, 179 deletions
diff --git a/cpp/doc/Makefile b/cpp/doc/Makefile index 664f17a69d6..55016ad0ebb 100644 --- a/cpp/doc/Makefile +++ b/cpp/doc/Makefile @@ -16,6 +16,7 @@ SLICEFILES = $(wildcard ../slice/Ice/*.ice) \ $(wildcard ../slice/IceBox/*.ice) \ $(wildcard ../slice/IceGrid/*.ice) \ $(wildcard ../slice/Glacier2/*.ice) \ + $(wildcard ../slice/IceSSL/*.ice) \ $(wildcard ../slice/IceStorm/*.ice) \ $(wildcard ../slice/IcePatch2/*.ice) @@ -23,7 +24,7 @@ include $(top_srcdir)/config/Make.rules reference/index.html: $(SLICEFILES) rm -rf reference - slice2html --ice -I../slice --header=htmlHeader --output-dir=reference --index=3 $(SLICEFILES) + slice2html --ice -I../slice --header=htmlHeader --output-dir=reference --index=3 --summary=120 $(SLICEFILES) clean:: rm -rf reference diff --git a/cpp/slice/Freeze/Evictor.ice b/cpp/slice/Freeze/Evictor.ice index acdad7b4665..164c6d80940 100644 --- a/cpp/slice/Freeze/Evictor.ice +++ b/cpp/slice/Freeze/Evictor.ice @@ -20,9 +20,8 @@ module Freeze /** * - * A servant initializer is installed in an evictor and provides the - * application with an opportunity to perform custom servant - * initialization. + * A servant initializer provides the application with an + * opportunity to perform custom servant initialization. * * @see Evictor * @@ -137,7 +136,7 @@ local interface Evictor extends Ice::ServantLocator * to set the queue size to a value smaller than zero are ignored. * * @param sz The size of the servant queue. If the evictor - * currently holds more than [sz] servants in its queue, it evicts + * currently holds more than <tt>sz</tt> servants in its queue, it evicts * enough servants to match the new size. Note that this operation * can block if the new queue size is smaller than the current * number of servants that are servicing requests. In this case, @@ -285,7 +284,7 @@ local interface Evictor extends Ice::ServantLocator /** * * Lock this object in the evictor cache. This lock can be released - * by [release] or remove. [release] releases only one lock, while + * by [release] or [remove]. [release] releases only one lock, while * [remove] releases all the locks. * * @param id The identity of the Ice object. @@ -327,14 +326,14 @@ local interface Evictor extends Ice::ServantLocator /** * - * Release a "lock" acquired by [keep]. Once all the locks on an + * Release a lock acquired by [keep]. Once all the locks on an * object have been released, the object is again subject to the * normal eviction strategy. * * @param id The identity of the Ice object. * * @throws NotRegisteredException Raised if this object was not - * "locked" with [keep] or [keepFacet]. + * locked with [keep] or [keepFacet]. * * @see keepFacet * @see release @@ -354,7 +353,7 @@ local interface Evictor extends Ice::ServantLocator * facet. * * @throws NotRegisteredException Raised if this object was not - * "locked" with [keep] or [keepFacet]. + * locked with [keep] or [keepFacet]. * * @see keep * @see releaseFacet diff --git a/cpp/slice/Freeze/EvictorStorage.ice b/cpp/slice/Freeze/EvictorStorage.ice index 569c5d03057..49d34d24c20 100644 --- a/cpp/slice/Freeze/EvictorStorage.ice +++ b/cpp/slice/Freeze/EvictorStorage.ice @@ -46,7 +46,7 @@ struct Statistics /** * - * The evictor uses a number of maps [Ice::Identity] to [ObjectRecord] as its + * The evictor uses a number of maps with [Ice::Identity] keys and [ObjectRecord] values as its * persistent storage. * **/ diff --git a/cpp/slice/Glacier2/Router.ice b/cpp/slice/Glacier2/Router.ice index 600e3043fd8..7be8aa6e7fe 100644 --- a/cpp/slice/Glacier2/Router.ice +++ b/cpp/slice/Glacier2/Router.ice @@ -57,7 +57,7 @@ exception SessionNotExistException /** * - * The Glacier2 specialization of the standard [Ice::Router] + * The Glacier2 specialization of the [Ice::Router] * interface. * **/ diff --git a/cpp/slice/Ice/Current.ice b/cpp/slice/Ice/Current.ice index 2fd44d3e8ad..4a91fe78da3 100644 --- a/cpp/slice/Ice/Current.ice +++ b/cpp/slice/Ice/Current.ice @@ -29,8 +29,7 @@ dictionary<string, string> Context; /** * - * The [OperationMode] determines the skeleton signature (for C++), as - * well as the retry behavior of the Ice run time for an operation + * The [OperationMode] determines the retry behavior an * invocation in case of a (potentially) recoverable error. * **/ @@ -57,6 +56,12 @@ enum OperationMode * run-time errors by re-issuing a failed request and propagate * the failure to the application only if the second attempt * fails. + * + * <p class="Deprecated"><tt>Nonmutating</tt> is deprecated; Use the + * <tt>idempotent</tt> keyword instead. For C++, to retain the mapping + * of <tt>nonmutating</tt> operations to C++ <tt>const</tt> + * member functions, use the <tt>\["cpp:const"]</tt> metadata + * directive.</p> */ \Nonmutating, diff --git a/cpp/slice/Ice/ImplicitContext.ice b/cpp/slice/Ice/ImplicitContext.ice index beb5143e5d6..bd8213c99c1 100644 --- a/cpp/slice/Ice/ImplicitContext.ice +++ b/cpp/slice/Ice/ImplicitContext.ice @@ -18,6 +18,8 @@ module Ice /** * + * An interface to associate implict contexts with communicators. + * * When you make a remote invocation without an explicit [Context] parameter, * Ice uses the per-proxy [Context] (if any) combined with the [ImplicitContext] * associated with the communicator.</dd> @@ -93,7 +95,7 @@ local interface ImplicitContext void set(string key, string value); /** - * Remove the value associated with the given key in the underlying context + * Remove the value associated with the given key in the underlying context. * Throws [NotSetException] when no value is associated with the given key. * * @param key The key. diff --git a/cpp/slice/Ice/LocalException.ice b/cpp/slice/Ice/LocalException.ice index e915e302604..e0c3738037a 100644 --- a/cpp/slice/Ice/LocalException.ice +++ b/cpp/slice/Ice/LocalException.ice @@ -59,6 +59,9 @@ local exception CollocationOptimizationException /** * + * An attempt was made to register something more than once with + * the Ice run time. + * * This exception is raised if an attempt is made to register a * servant, servant locator, facet, object factory, plug-in, object * adapter, object, or user exception factory more than once for the @@ -86,6 +89,9 @@ local exception AlreadyRegisteredException /** * + * An attempt was made to deregister something that is not + * registered with the Ice run time. + * * This exception is raised if an attempt is made to remove a servant, * facet, object factory, plug-in, object adapter, object, or user * exception factory that is not currently registered. @@ -112,6 +118,8 @@ local exception NotRegisteredException /** * + * The operation can only be invoked with a twoway request. + * * 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, @@ -130,6 +138,9 @@ local exception TwowayOnlyException /** * + * An attempt was made to clone a class that does not support + * cloning. + * * This exception is raised if [ice_clone] is called on * a class that is derived from an abstract Slice class (that is, * a class containing operations), and the derived class does not @@ -180,7 +191,9 @@ local exception UnknownLocalException extends UnknownException /** * - * This exception is raised if an operation call on a server raises a + * An operation raised an incorrect user exception. + * + * This exception is raised if an operation raises a * user exception that is not declared in the exception's * <tt>throws</tt> clause. Such undeclared exceptions are * not transmitted from the server to the client by the Ice @@ -237,8 +250,9 @@ local exception ObjectAdapterDeactivatedException /** * - * This exception is raised if an [ObjectAdapter] cannot be activated - * because the [Locator] detected another active [ObjectAdapter] with + * This exception is raised if an [ObjectAdapter] cannot be activated. + * + * This happens if the [Locator] detects another active [ObjectAdapter] with * the same adapter id. * **/ @@ -422,8 +436,7 @@ local exception SyscallException /** * - * This exception is a specialization of [SyscallException] for socket - * errors. + * This exception indicates socket errors. * **/ local exception SocketException extends SyscallException @@ -432,8 +445,7 @@ local exception SocketException extends SyscallException /** * - * This exception is a specialization of [SyscallException] for file - * errors. + * This exception indicates file errors. * **/ local exception FileException extends SyscallException @@ -444,8 +456,7 @@ local exception FileException extends SyscallException /** * - * This exception is a specialization of [SocketException] for - * connection failures. + * This exception indicates connection failures. * **/ local exception ConnectFailedException extends SocketException @@ -454,9 +465,8 @@ local exception ConnectFailedException extends SocketException /** * - * This exception is a specialization of [ConnectFailedException] for - * connection failures, where the server host actively refuses a - * connection. + * This exception indicates a connection failure for which + * the server host actively refuses a connection. * **/ local exception ConnectionRefusedException extends ConnectFailedException @@ -465,8 +475,7 @@ local exception ConnectionRefusedException extends ConnectFailedException /** * - * This exception is a specialization of [SocketException], indicating - * a lost connection. + * This exception indicates a lost connection. * **/ local exception ConnectionLostException extends SocketException @@ -510,8 +519,7 @@ local exception TimeoutException /** * - * This exception is a specialization of [TimeoutException] for - * connection establishment timeout conditions. + * This exception indicates a connection establishment timeout condition. * **/ local exception ConnectTimeoutException extends TimeoutException @@ -520,8 +528,7 @@ local exception ConnectTimeoutException extends TimeoutException /** * - * This exception is a specialization of [TimeoutException] for - * connection closure timeout conditions. + * This exception indicates a connection closure timeout condition. * **/ local exception CloseTimeoutException extends TimeoutException @@ -530,8 +537,7 @@ local exception CloseTimeoutException extends TimeoutException /** * - * This exception is a specialization of [TimeoutException], and - * indicates that a connection has been shut down because it has been + * This exception indicates that a connection has been shut down because it has been * idle for some time. * **/ @@ -557,8 +563,7 @@ local exception ProtocolException /** * - * This exception is a specialization of [ProtocolException], - * indicating that a message did not start with the expected + * This exception indicates that a message did not start with the expected * magic number ('I', 'c', 'e', 'P'). * **/ @@ -574,9 +579,7 @@ local exception BadMagicException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException], - * indicating that an unsupported protocol version has been - * encountered. + * This exception indicates an unsupported protocol version. * **/ local exception UnsupportedProtocolException extends ProtocolException @@ -612,9 +615,7 @@ local exception UnsupportedProtocolException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException], - * indicating that an unsupported data encoding version has been - * encountered. + * This exception indicates an unsupported data encoding version. * **/ local exception UnsupportedEncodingException extends ProtocolException @@ -650,8 +651,7 @@ local exception UnsupportedEncodingException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException], - * indicating that an unknown protocol message has been received. + * This exception indicates that an unknown protocol message has been received. * **/ local exception UnknownMessageException extends ProtocolException @@ -660,9 +660,8 @@ local exception UnknownMessageException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException], that is - * raised if a message is received over a connection that is not yet - * validated. + * This exception is raised if a message is received over a connection + * that is not yet validated. * **/ local exception ConnectionNotValidatedException extends ProtocolException @@ -671,8 +670,7 @@ local exception ConnectionNotValidatedException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException], - * indicating that a response for an unknown request ID has been + * This exception indicates that a response for an unknown request ID has been * received. * **/ @@ -682,8 +680,7 @@ local exception UnknownRequestIdException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException], - * indicating that an unknown reply status has been received. + * This exception indicates that an unknown reply status has been received. * **/ local exception UnknownReplyStatusException extends ProtocolException @@ -692,8 +689,7 @@ local exception UnknownReplyStatusException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException], - * indicating that the connection has been gracefully shut down by the + * This exception indicates that the connection has been gracefully shut down by the * server. The operation call that caused this exception has not been * executed by the server. In most cases you will not get this * exception, because the client will automatically retry the @@ -710,8 +706,7 @@ local exception CloseConnectionException extends ProtocolException /** * * This exception is raised by an operation call if the application - * forcefully closes the connection used by this call with - * [Connection::close]. + * forcefully closes the connection [Connection::close]. * * @see Connection::close * @@ -722,9 +717,8 @@ local exception ForcedCloseConnectionException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException], - * indicating that the message size is illegal, i.e., it is - * less than the minimum required size. + * This exception indicates that a message size is less + * than the minimum required size. * **/ local exception IllegalMessageSizeException extends ProtocolException @@ -733,9 +727,7 @@ local exception IllegalMessageSizeException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException] that is - * raised if there is a problem with compressing or uncompressing - * data. + * This exception indicates a problem with compressing or uncompressing data. * **/ local exception CompressionException extends ProtocolException @@ -744,8 +736,9 @@ local exception CompressionException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException] that is - * raised if a datagram exceeds the configured send or receive buffer + * A datagram exceeds the configured size. + * + * This exception is raised if a datagram exceeds the configured send or receive buffer * size, or exceeds the maximum payload size of a UDP packet (65507 bytes). * **/ @@ -755,8 +748,7 @@ local exception DatagramLimitException extends ProtocolException /** * - * This exception is a specialization of [ProtocolException] that is - * raised upon an error during marshaling or unmarshaling data. + * This exception is raised for errors during marshaling or unmarshaling data. * **/ local exception MarshalException extends ProtocolException @@ -765,8 +757,7 @@ local exception MarshalException extends ProtocolException /** * - * This exception is a specialization of [MarshalException] that is - * raised if inconsistent data is received while unmarshaling a proxy. + * This exception is raised if inconsistent data is received while unmarshaling a proxy. * **/ local exception ProxyUnmarshalException extends MarshalException @@ -775,8 +766,7 @@ local exception ProxyUnmarshalException extends MarshalException /** * - * This exception is a specialization of [MarshalException] that is - * raised if an out-of-bounds condition occurs during unmarshaling. + * This exception is raised if an out-of-bounds condition occurs during unmarshaling. * **/ local exception UnmarshalOutOfBoundsException extends MarshalException @@ -785,8 +775,7 @@ local exception UnmarshalOutOfBoundsException extends MarshalException /** * - * This exception is a specialization of [MarshalException], - * indicating an illegal indirection during unmarshaling. + * This exception indicates an illegal indirection during unmarshaling. * **/ local exception IllegalIndirectionException extends MarshalException @@ -795,8 +784,7 @@ local exception IllegalIndirectionException extends MarshalException /** * - * This exception is a specialization of [MarshalException] that is - * raised if no suitable object factory was found during + * This exception is raised if no suitable object factory was found during * unmarshaling of a Slice class instance. * * @see ObjectFactory @@ -817,9 +805,8 @@ local exception NoObjectFactoryException extends MarshalException /** * - * This exception is a specialization of [MarshalException] that is - * raised if the type of an unmarshaled Slice class instance does - * not match the type excepted by an operation that is passed that instance. + * This exception is raised if the type of an unmarshaled Slice class instance does + * not match its expected type. * This can happen if client and server are compiled with mismatched Slice * definitions or if a class of the wrong type is passed as a parameter * or return value using dynamic invocation. This exception can also be @@ -846,8 +833,7 @@ local exception UnexpectedObjectException extends MarshalException /** * - * This exception is a specialization of [MarshalException] that is - * raised if the system-specific memory limit is exceeded during + * This exception is raised if the system-specific memory limit is exceeded during * marshaling or unmarshaling. * **/ @@ -857,7 +843,7 @@ local exception MemoryLimitException extends MarshalException /** * - * This exception is a specialization of [MarshalException] that is + * This exception is * raised when a string conversion to or from UTF-8 fails during * marshaling or unmarshaling. * @@ -869,8 +855,7 @@ local exception StringConversionException extends MarshalException /** * - * This exception is a specialization of [MarshalException], - * indicating a malformed data encapsulation. + * This exception indicates a malformed data encapsulation. * **/ local exception EncapsulationException extends MarshalException @@ -879,9 +864,8 @@ local exception EncapsulationException extends MarshalException /** * - * This exception is a specialization of [MarshalException] that is - * raised if a negative size (e.g., a negative sequence size) is - * received. + * This exception is raised if a negative size + * (e.g., 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 08b2f781ad4..f4cd44d459b 100644 --- a/cpp/slice/Ice/ObjectAdapter.ice +++ b/cpp/slice/Ice/ObjectAdapter.ice @@ -22,7 +22,10 @@ module Ice /** * - * The object adapter, which is responsible for receiving requests + * The object adapter provides an up-call interface from the Ice + * run time to the implementation of Ice objects. + * + * The object adapter is responsible for receiving requests * from endpoints, and for mapping between servants, identities, and * proxies. * @@ -275,8 +278,8 @@ local interface ObjectAdapter /** * * Remove all facets with the given identity from the Active - * Servant Map (that is, completely remove the Ice object, - * including its default facet). Removing an identity that + * Servant Map. The operation completely removes the Ice object, + * including its default facet. Removing an identity that * is not in the map throws [NotRegisteredException]. * * @param id The identity of the Ice object to be removed. diff --git a/cpp/slice/Ice/Properties.ice b/cpp/slice/Ice/Properties.ice index 45c2c1258c0..cb77a6271aa 100644 --- a/cpp/slice/Ice/Properties.ice +++ b/cpp/slice/Ice/Properties.ice @@ -159,8 +159,7 @@ local interface Properties * Convert a sequence of command-line options into properties. * All options that begin with one of the following prefixes * are converted into properties: [--Ice], [--IceBox], [--IceGrid], - * [--IcePatch], [--IcePatch2], [--IceSSL], [--IceStorm], [--Freeze], - * [--Glacier], and [--Glacier2]. + * [--IcePatch2], [--IceSSL], [--IceStorm], [--Freeze], and [--Glacier2]. * * @param options The command-line options. * diff --git a/cpp/slice/Ice/Router.ice b/cpp/slice/Ice/Router.ice index a939d44fd8b..673a362d60e 100644 --- a/cpp/slice/Ice/Router.ice +++ b/cpp/slice/Ice/Router.ice @@ -48,7 +48,7 @@ interface Router * * Add new proxy information to the router's routing table. * - * <p class="Note">This operation is deprecated, and only used for old + * <p class="Deprecated">This operation is deprecated, and only used for old * Ice clients (older than version 3.1).</p> * * @param proxy The proxy to add. diff --git a/cpp/slice/Ice/ServantLocator.ice b/cpp/slice/Ice/ServantLocator.ice index d1b3a2ac8ce..9136fddd6ac 100644 --- a/cpp/slice/Ice/ServantLocator.ice +++ b/cpp/slice/Ice/ServantLocator.ice @@ -18,7 +18,7 @@ module Ice /** * - * The servant locator, which is called by the object adapter to + * A servant locator is called by an object adapter to * locate a servant that is not found in its active servant map. * * @see ObjectAdapter @@ -30,7 +30,7 @@ local interface ServantLocator { /** * - * Called by the object adapter before a request is made when a + * Called before a request is dispatched if a * servant cannot be found in the object adapter's active servant * map. Note that the object adapter does not automatically insert * the returned servant into its active servant map. This must be diff --git a/cpp/slice/IceGrid/Admin.ice b/cpp/slice/IceGrid/Admin.ice index 7351039e7b7..7df9e0839a4 100644 --- a/cpp/slice/IceGrid/Admin.ice +++ b/cpp/slice/IceGrid/Admin.ice @@ -1108,8 +1108,8 @@ interface ObjectObserver; /** * - * An admin session object used by administrative clients to view, - * update and receive observer updates from the IceGrid + * Used by administrative clients to view, + * update, and receive observer updates from the IceGrid * registry. Admin sessions are created either with the [Registry] * object or the registry admin [Glacier2::SessionManager] object. * @@ -1141,8 +1141,8 @@ interface AdminSession extends Glacier2::Session /** * - * Set the proxies of the observer objects that will receive - * notifications from the servers when the state of the registry + * Set the observer proxies that receive + * notifications when the state of the registry * or nodes changes. * * @param registryObs The registry observer. @@ -1165,8 +1165,8 @@ interface AdminSession extends Glacier2::Session /** * - * Set the identities of the observer objects that will receive - * notifications from the servers when the state of the registry + * Set the observer identities that receive + * notifications the state of the registry * or nodes changes. This operation should be used by clients that * are using a bidirectional connection to communicate with the * session. diff --git a/cpp/slice/IceGrid/Exception.ice b/cpp/slice/IceGrid/Exception.ice index cd69a7b46d6..65d53c2b356 100644 --- a/cpp/slice/IceGrid/Exception.ice +++ b/cpp/slice/IceGrid/Exception.ice @@ -33,7 +33,11 @@ exception ApplicationNotExistException **/ exception ServerNotExistException { - /** The identifier of the server. */ + /** + * + * The identifier of the server. + * + */ string id; }; @@ -44,10 +48,18 @@ exception ServerNotExistException **/ exception ServerStartException { - /** The identifier of the server. */ + /** + * + * The identifier of the server. + * + **/ string id; - /** The reason for the failure. */ + /** + * + * The reason for the failure. + * + **/ string reason; }; @@ -58,10 +70,18 @@ exception ServerStartException **/ exception ServerStopException { - /** The identifier of the server. */ + /** + * + * The identifier of the server. + * + **/ string id; - /** The reason for the failure. */ + /** + * + * The reason for the failure. + * + **/ string reason; }; @@ -72,7 +92,11 @@ exception ServerStopException **/ exception AdapterNotExistException { - /** The id of the object adapter. */ + /** + * + * The id of the object adapter. + * + **/ string id; }; @@ -138,10 +162,18 @@ exception DeploymentException **/ exception NodeUnreachableException { - /** The name of the node that is not reachable. */ + /** + * + * The name of the node that is not reachable. + * + **/ string name; - /** The reason why the node couldn't be reached. */ + /** + * + * The reason why the node couldn't be reached. + * + **/ string reason; }; @@ -152,10 +184,18 @@ exception NodeUnreachableException **/ exception RegistryUnreachableException { - /** The name of the registry that is not reachable. */ + /** + * + * The name of the registry that is not reachable. + * + **/ string name; - /** The reason why the registry couldn't be reached. */ + /** + * + * The reason why the registry couldn't be reached. + * + **/ string reason; }; @@ -167,6 +207,11 @@ exception RegistryUnreachableException **/ exception BadSignalException { + /** + * + * The details of the unknown signal. + * + **/ string reason; }; @@ -177,18 +222,27 @@ exception BadSignalException **/ exception PatchException { - /** The reasons why the patch failed. */ + /** + * + * The reasons why the patch failed. + * + **/ Ice::StringSeq reasons; }; /** * - * This exception is raised if an operation can't be performed because - * the registry lock wasn't acquired or is already acquired by a session. + * This exception is raised if a registry lock wasn't + * acquired or is already held by a session. * **/ exception AccessDeniedException { + /** + * + * The id of the user holding the lock (if any). + * + **/ string lockUserId; }; @@ -199,7 +253,11 @@ exception AccessDeniedException **/ exception AllocationException { - /** The reason why the object couldn't be allocated. */ + /** + * + * The reason why the object couldn't be allocated. + * + **/ string reason; }; diff --git a/cpp/slice/IceGrid/FileParser.ice b/cpp/slice/IceGrid/FileParser.ice index d6a3397496e..d697d12a4ec 100755 --- a/cpp/slice/IceGrid/FileParser.ice +++ b/cpp/slice/IceGrid/FileParser.ice @@ -28,9 +28,9 @@ exception ParseException /**
*
- * The icegridadmin command line tool provides a [FileParser] object
- * to transform XML files into [ApplicationDescriptor] objects
- * (structs).
+ * <tt>icegridadmin</tt> provides a [FileParser]
+ * object to transform XML files into [ApplicationDescriptor]
+ * objects.
*
**/
interface FileParser
diff --git a/cpp/slice/IceGrid/Locator.ice b/cpp/slice/IceGrid/Locator.ice index 947bde7fc47..d8c7b1ba723 100644 --- a/cpp/slice/IceGrid/Locator.ice +++ b/cpp/slice/IceGrid/Locator.ice @@ -20,12 +20,11 @@ interface Query; /** * - * The IceGrid locator interface extends the [Ice::Locator] interface - * to provide access to the IceGrid query and registry object of the - * IceGrid registry. + * The IceGrid locator interface provides access to the [Query] + * and [Registry] object of the IceGrid registry. * - * @see Registry * @see Query + * @see Registry * **/ interface Locator extends Ice::Locator diff --git a/cpp/slice/IceGrid/Observer.ice b/cpp/slice/IceGrid/Observer.ice index caf673b746f..2f9223bd249 100644 --- a/cpp/slice/IceGrid/Observer.ice +++ b/cpp/slice/IceGrid/Observer.ice @@ -137,9 +137,8 @@ interface NodeObserver { /** * - * The nodeInit operation is called after the registration of the - * observer to communicate the current state of the nodes to the - * observer implementation. + * The <tt>nodeInit</tt> operation indicates the current state + * of nodes. It is called after the registration of an observer. * * @param nodes The current state of the nodes. * @@ -148,7 +147,7 @@ interface NodeObserver /** * - * The nodeUp operation is called to notify the observer that a node + * The <tt>nodeUp</tt> operation is called to notify an observer that a node * came up. * * @param node The node state. @@ -158,7 +157,7 @@ interface NodeObserver /** * - * The nodeDown operation is called to notify the observer that a node + * The <tt>nodeDown</tt> operation is called to notify an observer that a node * went down. * * @param name The node name. @@ -168,7 +167,7 @@ interface NodeObserver /** * - * The updateServer operation is called to notify the observer that + * The <tt>updateServer</tt> operation is called to notify an observer that * the state of a server changed. * * @param node The node hosting the server. @@ -180,7 +179,7 @@ interface NodeObserver /** * - * The updateAdapter operation is called to notify the observer that + * The <tt>updateAdapter</tt> operation is called to notify an observer that * the state of an adapter changed. * * @param node The node hosting the adapter. @@ -202,9 +201,8 @@ interface ApplicationObserver { /** * - * The applicationInit operation is called after the registration - * of the observer to communicate the current state of the - * registry to the observer implementation. + * <tt>applicationInit</tt> is called after the registration + * of an observer to indicate the state of the registry. * * @param serial The current serial number of the registry * database. This serial number allows observers to make sure that @@ -218,7 +216,7 @@ interface ApplicationObserver /** * - * The applicationAdded operation is called to notify the observer + * The <tt>applicationAdded</tt> operation is called to notify an observer * that an application was added. * * @param serial The new serial number of the registry database. @@ -230,7 +228,7 @@ interface ApplicationObserver /** * - * The applicationRemoved operation is called to notify the observer + * The <tt>applicationRemoved</tt> operation is called to notify an observer * that an application was removed. * * @param serial The new serial number of the registry database. @@ -242,7 +240,7 @@ interface ApplicationObserver /** * - * The applicationUpdated operation is called to notify the observer + * The <tt>applicationUpdated</tt> operation is called to notify an observer * that an application was updated. * * @param serial The new serial number of the registry database. @@ -257,9 +255,8 @@ interface AdapterObserver { /** * - * The adapterInit operation is called after the registration of - * the observer to communicate the current state of the registry - * to the observer implementation. + * <tt>adapterInit</tt> is called after registration of + * an observer to indicate the state of the registry. * * @param serial The current serial number of the registry * database. This serial number allows observers to make sure that @@ -273,7 +270,7 @@ interface AdapterObserver /** * - * The adapterAdded operation is called to notify the observer when + * The <tt>adapterAdded</tt> operation is called to notify an observer when * a dynamically-registered adapter was added. * **/ @@ -281,7 +278,7 @@ interface AdapterObserver /** * - * The adapterUpdated operation is called to notify the observer when + * The adapterUpdated operation is called to notify an observer when * a dynamically-registered adapter was updated. * **/ @@ -289,7 +286,7 @@ interface AdapterObserver /** * - * The adapterRemoved operation is called to notify the observer when + * The adapterRemoved operation is called to notify an observer when * a dynamically-registered adapter was removed. * **/ @@ -300,9 +297,8 @@ interface ObjectObserver { /** * - * The objectInit operation is called after the registration of - * the observer to communicate the current state of the registry - * to the observer implementation. + * <tt>objectInit</tt> is called after the registration of + * an observer to indicate the state of the registry. * * @param serial The current serial number of the registry database. This * serial number allows observers to make sure that their internal state @@ -316,24 +312,24 @@ interface ObjectObserver /** * - * The objectAdded operation is called to notify the observer when an - * object was added through the [Admin] interface. + * The <tt>objectAdded</tt> operation is called to notify an observer when an + * object was added to the [Admin] interface. * **/ void objectAdded(ObjectInfo info); /** * - * The objectUpdated operation is called to notify the observer when - * an object registered through the [Admin] interface was updated. + * <tt>objectUpdated</tt> is called to notify an observer when + * an object registered with the [Admin] interface was updated. * **/ void objectUpdated(ObjectInfo info); /** * - * The objectRemoved operation is called to notify the observer when - * an object registered through the [Admin] interface was removed. + * <tt>objectRemoved</tt> is called to notify an observer when + * an object registered with the [Admin] interface was removed. * **/ void objectRemoved(Ice::Identity id); @@ -343,9 +339,8 @@ interface RegistryObserver { /** * - * The registryInit operation is called after the registration of - * the observer to communicate the current state of the registries - * to the observer implementation. + * <tt>registryInit</ttoperation is called after the registration of + * an observer to indicate the state of the registries. * * @param registries The current state of the registries. * @@ -354,7 +349,7 @@ interface RegistryObserver /** * - * The nodeUp operation is called to notify the observer that a node + * The <tt>nodeUp</tt> operation is called to notify an observer that a node * came up. * * @param node The node state. @@ -364,7 +359,7 @@ interface RegistryObserver /** * - * The nodeDown operation is called to notify the observer that a node + * The <tt>nodeDown</tt> operation is called to notify an observer that a node * went down. * * @param name The node name. diff --git a/cpp/slice/IceGrid/Registry.ice b/cpp/slice/IceGrid/Registry.ice index eee50e8ec83..067f9d632eb 100644 --- a/cpp/slice/IceGrid/Registry.ice +++ b/cpp/slice/IceGrid/Registry.ice @@ -19,9 +19,8 @@ module IceGrid /** * - * The IceGrid registry provides a registry object to allow clients - * or administrative clients to create sessions directly with the - * registry. + * The IceGrid registry allows clients create sessions + * directly with the registry. * * @see Session * @see AdminSession diff --git a/cpp/slice/IceGrid/UserAccountMapper.ice b/cpp/slice/IceGrid/UserAccountMapper.ice index 8b202a05515..c6c7b7f78a8 100644 --- a/cpp/slice/IceGrid/UserAccountMapper.ice +++ b/cpp/slice/IceGrid/UserAccountMapper.ice @@ -40,7 +40,7 @@ interface UserAccountMapper * @param user The value of the server descriptor's <tt>user</tt> * attribute. If this attribute is not defined, and the server's * activation mode is <tt>session</tt>, the default value of - * [user] is the session identifier. + * <tt>user</tt> is the session identifier. * * @return The user account name. * diff --git a/cpp/slice/IcePatch2/FileServer.ice b/cpp/slice/IcePatch2/FileServer.ice index 2862672def0..4c059aa79af 100644 --- a/cpp/slice/IcePatch2/FileServer.ice +++ b/cpp/slice/IcePatch2/FileServer.ice @@ -32,8 +32,8 @@ sequence<Ice::ByteSeq> ByteSeqSeq; /** * - * This exception is raised if the [partition] argument for - * [getFileInfoSeq] is not in the range 0-255. + * The [partition] argument for + * [FileServer::getFileInfoSeq] was not in the range 0-255. * **/ exception PartitionOutOfRangeException @@ -42,7 +42,7 @@ exception PartitionOutOfRangeException /** * - * This exception is raised if [getFileCompressed] cannot read the + * This exception is raised if [FileServer::getFileCompressed] cannot read the * contents of a file. * **/ @@ -56,6 +56,11 @@ exception FileAccessException string reason; }; +/** + * + * The interface that provides access to files. + * + **/ interface FileServer { /** diff --git a/cpp/slice/IceStorm/IceStorm.ice b/cpp/slice/IceStorm/IceStorm.ice index 82333eb5e7f..04c4fc35c37 100644 --- a/cpp/slice/IceStorm/IceStorm.ice +++ b/cpp/slice/IceStorm/IceStorm.ice @@ -64,7 +64,7 @@ sequence<LinkInfo> LinkInfoSeq; /** * - * This dictionary represents Quality of service parameters. + * This dictionary represents quality of service parameters. * * @see Topic::subscribe * @@ -148,8 +148,8 @@ interface Topic /** * - * Subscribe with the given [qos] to this topic. If the given - * [subscriber] proxy has already been registered, it will be + * Subscribe with the given <tt>qos</tt> to this topic. If the given + * <tt>subscriber</tt> proxy has already been registered, it will be * replaced. Note that this can cause a loss of events to the * subscribed object. * @@ -167,8 +167,8 @@ interface Topic /** * - * Subscribe with the given [qos] to this topic. If the given - * [subscriber] proxy has already been registered, it will be + * Subscribe with the given <tt>qos</tt> to this topic. If the given + * <tt>subscriber</tt> proxy has already been registered, it will be * replaced. A per-subscriber publisher object is returned. * * @param qos The quality of service parameters for this @@ -189,7 +189,7 @@ interface Topic /** * - * Unsubscribe the given [subscriber]. + * Unsubscribe the given <tt>subscriber</tt>. * * @param subscriber The proxy of an existing subscriber. * @@ -201,7 +201,7 @@ interface Topic /** * * Create a link to the given topic. All events originating - * on this topic will also be sent to [linkTo]. + * on this topic will also be sent to <tt>linkTo</tt>. * * @param linkTo The topic to link to. * @@ -215,7 +215,7 @@ interface Topic /** * - * Destroy the link from this topic to the given topic [linkTo]. + * Destroy the link from this topic to the given topic <tt>linkTo</tt>. * * @param link The topic to destroy the link to. * diff --git a/cpp/src/slice2html/Gen.cpp b/cpp/src/slice2html/Gen.cpp index 05ccdd14f60..7a8e8847f02 100644 --- a/cpp/src/slice2html/Gen.cpp +++ b/cpp/src/slice2html/Gen.cpp @@ -33,7 +33,7 @@ namespace Slice void generate(const UnitPtr& unit, const ::std::string& dir, - const ::std::string& header, const ::std::string& footer, unsigned indexCount) + const ::std::string& header, const ::std::string& footer, unsigned indexCount, unsigned warnSummary) { unit->mergeModules(); @@ -47,6 +47,7 @@ generate(const UnitPtr& unit, const ::std::string& dir, GeneratorBase::setHeader(header); GeneratorBase::setFooter(footer); GeneratorBase::setIndexCount(indexCount); + GeneratorBase::warnSummary(warnSummary); // // The types visitor first runs over the tree and records @@ -81,6 +82,7 @@ string Slice::GeneratorBase::_header1; string Slice::GeneratorBase::_header2; string Slice::GeneratorBase::_footer; unsigned Slice::GeneratorBase::_indexCount = 0; +unsigned Slice::GeneratorBase::_warnSummary = 0; // // Set the output directory, creating it if necessary. @@ -173,6 +175,16 @@ Slice::GeneratorBase::setIndexCount(int ic) _indexCount = ic; } +// +// If n > 0, we print a warning if a summary sentence exceeds n characters. +// + +void +Slice::GeneratorBase::warnSummary(int n) +{ + _warnSummary = n; +} + Slice::GeneratorBase::GeneratorBase(XMLOutput& o, const Files& files) : _out(o), _files(files) { @@ -551,7 +563,8 @@ Slice::GeneratorBase::printSummary(const ContainedPtr& p, const ContainerPtr& mo } string -Slice::GeneratorBase::toString(const SyntaxTreeBasePtr& p, const ContainerPtr& container, bool asTarget, bool inIndex) +Slice::GeneratorBase::toString(const SyntaxTreeBasePtr& p, const ContainerPtr& container, bool asTarget, bool inIndex, + unsigned* summarySize) { string anchor; string linkpath; @@ -686,11 +699,17 @@ Slice::GeneratorBase::toString(const SyntaxTreeBasePtr& p, const ContainerPtr& c s = getScopedMinimized(contained, container); } + if(summarySize) + { + *summarySize = s.size(); + } + if(linkpath.empty() && anchor.empty()) { if(ProxyPtr::dynamicCast(p)) { s += '*'; + ++(*summarySize); } return s; } @@ -725,20 +744,21 @@ Slice::GeneratorBase::toString(const SyntaxTreeBasePtr& p, const ContainerPtr& c } string -Slice::GeneratorBase::toString(const string& str, const ContainerPtr& container, bool asTarget, bool inIndex) +Slice::GeneratorBase::toString(const string& str, const ContainerPtr& container, bool asTarget, bool inIndex, + unsigned* summarySize) { string s = str; TypeList types = container->lookupType(s, false); if(!types.empty()) { - return toString(types.front(), container, asTarget, inIndex); + return toString(types.front(), container, asTarget, inIndex, summarySize); } ContainedList contList = container->lookupContained(s, false); if(!contList.empty()) { - return toString(contList.front(), container, asTarget, inIndex); + return toString(contList.front(), container, asTarget, inIndex, summarySize); } // @@ -752,6 +772,7 @@ string Slice::GeneratorBase::getComment(const ContainedPtr& contained, const ContainerPtr& container, bool summary, bool inIndex) { + unsigned summarySize = 0; string s = contained->comment(); string comment; for(unsigned int i = 0; i < s.size(); ++i) @@ -759,6 +780,7 @@ Slice::GeneratorBase::getComment(const ContainedPtr& contained, const ContainerP if(s[i] == '\\' && i + 1 < s.size() && s[i + 1] == '[') { comment += '['; + ++summarySize; ++i; } else if(s[i] == '[') @@ -773,19 +795,29 @@ Slice::GeneratorBase::getComment(const ContainedPtr& contained, const ContainerP literal += s[i]; } - comment += toString(literal, container, false, inIndex); + unsigned sz = 0; + comment += toString(literal, container, false, inIndex, summary ? &sz : 0); + summarySize += sz; } else if(summary && s[i] == '.' && (i + 1 >= s.size() || isspace(s[i + 1]))) { comment += '.'; + ++summarySize; break; } else { comment += s[i]; + ++summarySize; } + } + if(summary && _warnSummary && summarySize > _warnSummary) + { + cerr << contained->definitionContext()->filename() << ": summary size (" << summarySize << ") exceeds " + << _warnSummary << " characters: `" << comment << "'" << endl; } + return comment; } @@ -1288,7 +1320,7 @@ Slice::ModuleGenerator::generate(const ModulePtr& m) openDoc(m); start("h1", "Symbol"); - _out << toString(m, m, true); + _out << toString(m, m->container(), true); end(); string metadata, deprecateReason; diff --git a/cpp/src/slice2html/Gen.h b/cpp/src/slice2html/Gen.h index 2f459431078..a4a2ad1edbc 100644 --- a/cpp/src/slice2html/Gen.h +++ b/cpp/src/slice2html/Gen.h @@ -16,7 +16,7 @@ namespace Slice { -void generate(const UnitPtr&, const ::std::string&, const ::std::string&, const ::std::string&, unsigned); +void generate(const UnitPtr&, const ::std::string&, const ::std::string&, const ::std::string&, unsigned, unsigned); typedef ::std::set< ::std::string> Files; @@ -27,7 +27,8 @@ public: static void setOutputDir(const ::std::string&); static void setHeader(const ::std::string&); static void setFooter(const ::std::string&); - static void setIndexCount(const int); + static void setIndexCount(int); + static void warnSummary(int); protected: @@ -45,8 +46,8 @@ protected: void printMetaData(const ContainedPtr&); void printSummary(const ContainedPtr&, const ContainerPtr&, bool); - ::std::string toString(const SyntaxTreeBasePtr&, const ContainerPtr&, bool = true, bool = false); - ::std::string toString(const ::std::string&, const ContainerPtr&, bool = true, bool = false); + ::std::string toString(const SyntaxTreeBasePtr&, const ContainerPtr&, bool = true, bool = false, unsigned* = 0); + ::std::string toString(const ::std::string&, const ContainerPtr&, bool = true, bool = false, unsigned* = 0); ::std::string getComment(const ContainedPtr&, const ContainerPtr&, bool, bool = false); static ::std::string getAnchor(const SyntaxTreeBasePtr&); @@ -55,6 +56,7 @@ protected: ::IceUtil::XMLOutput& _out; static unsigned _indexCount; + static unsigned _warnSummary; private: diff --git a/cpp/src/slice2html/Main.cpp b/cpp/src/slice2html/Main.cpp index dd3d4393ab6..a230bd0eb47 100644 --- a/cpp/src/slice2html/Main.cpp +++ b/cpp/src/slice2html/Main.cpp @@ -33,6 +33,7 @@ usage(const char* n) "--header FILE Use the contents of FILE as the header.\n" "--footer FILe Use the contents of FILE as the footer.\n" "--index NUM Generate subindex if it has at least NUM entries (0 for no index, default=1).\n" + "--summary NUM Print a warning if a summary sentence exceeds NUM characters.\n" "-d, --debug Print debug messages.\n" "--ice Permit `Ice' prefix (for building Ice source code only).\n" ; @@ -52,6 +53,7 @@ main(int argc, char* argv[]) opts.addOpt("", "header", IceUtil::Options::NeedArg); opts.addOpt("", "footer", IceUtil::Options::NeedArg); opts.addOpt("", "index", IceUtil::Options::NeedArg, "1"); + opts.addOpt("", "summary", IceUtil::Options::NeedArg, "0"); opts.addOpt("d", "debug"); opts.addOpt("", "ice"); @@ -121,6 +123,20 @@ main(int argc, char* argv[]) } } + string warnSummary = opts.optArg("summary"); + unsigned summaryCount; + if(!warnSummary.empty()) + { + istringstream s(warnSummary); + s >> summaryCount; + if(!s) + { + cerr << argv[0] << ": the --summary operation requires a positive integer argument" << endl; + usage(argv[0]); + return EXIT_FAILURE; + } + } + bool debug = opts.isSet("debug"); bool ice = opts.isSet("ice"); @@ -174,7 +190,7 @@ main(int argc, char* argv[]) { try { - Slice::generate(p, output, header, footer, indexCount); + Slice::generate(p, output, header, footer, indexCount, summaryCount); } catch(const string& err) { |