Improve C# Doc-Comments to Match C++ and Java

cpp/include/Ice/Communicator.h

@@ -37,7 +37,7 @@ namespace Ice
         ~Communicator();
 
         /// Destroys this communicator. This function calls #shutdown implicitly. Calling #destroy destroys all
-        /// object adapters, and closes all outgoing connections. `destroy` waits for all outstanding dispatches to
+        /// object adapters, and closes all outgoing connections. This method waits for all outstanding dispatches to
         /// complete before returning. This includes "bidirectional dispatches" that execute on outgoing connections.
         /// @see CommunicatorHolder
         void destroy() noexcept;

cpp/include/Ice/Connection.h

@@ -99,14 +99,14 @@ namespace Ice
         /// @return The endpoint from which the connection was created.
         [[nodiscard]] virtual EndpointPtr getEndpoint() const noexcept = 0;
 
-        /// Flushes any pending batch requests for this connection. This corresponds to all batch requests invoked on
-        /// fixed proxies associated with the connection.
+        /// Flushes any pending batch requests for this connection.
+        /// This means all batch requests invoked on fixed proxies associated with the connection.
         /// @param compress Specifies whether or not the queued batch requests should be compressed before being sent
         /// over the wire.
         void flushBatchRequests(CompressBatch compress);
 
-        /// Flushes any pending batch requests for this connection. This corresponds to all batch requests invoked on
-        /// fixed proxies associated with the connection.
+        /// Flushes any pending batch requests for this connection.
+        /// This means all batch requests invoked on fixed proxies associated with the connection.
         /// @param compress Specifies whether or not the queued batch requests should be compressed before being sent
         /// over the wire.
         /// @param exception The exception callback.

cpp/include/Ice/Current.h

@@ -28,7 +28,7 @@ namespace Ice
         /// The facet of the target Ice object.
         std::string facet;
 
-        /// The operation name.
+        /// The name of the operation.
         std::string operation;
 
         /// The mode of the operation (see ::Ice::checkNonIdempotent).

cpp/include/Ice/Endpoint.h

@@ -155,7 +155,7 @@ namespace Ice
         const bool _secure;
     };
 
-    /// Provides access to an UDP endpoint information.
+    /// Provides access to a UDP endpoint information.
     /// @see Endpoint
     /// @headerfile Ice/Ice.h
     class ICE_API UDPEndpointInfo final : public IPEndpointInfo

cpp/include/Ice/Exception.h

@@ -32,7 +32,7 @@ namespace Ice
         ~Exception() override;
 
         /// Returns the type ID of this exception. This corresponds to the Slice type ID for Slice-defined exceptions,
-        /// and to a similar fully scoped name for other exceptions. For example
+        /// and to a fully scoped name for other exceptions. For example
         /// "::Ice::CommunicatorDestroyedException".
         /// @return The type ID of this exception
         [[nodiscard]] virtual const char* ice_id() const noexcept = 0;

cpp/include/Ice/IncomingRequest.h

@@ -57,7 +57,7 @@ namespace Ice
 
         /// Gets the number of bytes in the request.
         /// @return The number of bytes in the request. These are all the bytes starting with the identity of the
-        /// target.
+        /// target object.
         [[nodiscard]] std::int32_t size() const { return _requestSize; }
 
         /// Gets the request count.

cpp/include/Ice/Initialize.h

@@ -27,7 +27,7 @@ namespace Ice
     struct InitializationData
     {
         /// The properties for the communicator.
-        /// When not-null, this corresponds to the object returned by the Communicator::getProperties function.
+        /// When non-null, this corresponds to the object returned by the Communicator::getProperties function.
         PropertiesPtr properties{};
 
         /// The logger for the communicator.

cpp/include/Ice/Instrumentation.h

@@ -102,7 +102,7 @@ namespace Ice::Instrumentation
         ConnectionStateClosed
     };
 
-    /// Represents the base class for Ice observers.
+    /// The base class for Ice observers.
     /// @headerfile Ice/Ice.h
     class Observer
     {

cpp/include/Ice/LocalExceptions.h

@@ -101,7 +101,7 @@ namespace Ice
         std::shared_ptr<std::string> _operation;
     };
 
-    /// The exception that is thrown when a dispatch cannot find a servant for the identity carried by the request.
+    /// The exception that is thrown when a dispatch could not find a servant for the identity carried by the request.
     /// @headerfile Ice/Ice.h
     class ICE_API ObjectNotExistException final : public RequestFailedException
     {
@@ -123,7 +123,7 @@ namespace Ice
         [[nodiscard]] const char* ice_id() const noexcept final;
     };
 
-    /// The exception that is thrown when a dispatch cannot find a servant for the identity + facet carried by the
+    /// The exception that is thrown when a dispatch could not find a servant for the identity + facet carried by the
     /// request.
     /// @headerfile Ice/Ice.h
     class ICE_API FacetNotExistException final : public RequestFailedException
@@ -146,7 +146,7 @@ namespace Ice
         [[nodiscard]] const char* ice_id() const noexcept final;
     };
 
-    /// The exception that is thrown when a dispatch cannot find the operation carried by the request on the target
+    /// The exception that is thrown when a dispatch could not find the operation carried by the request on the target
     /// servant. This is typically due to a mismatch in the Slice definitions, such as the client using Slice
     /// definitions newer than the server's.
     /// @headerfile Ice/Ice.h

cpp/include/Ice/MarshaledResult.h

@@ -9,8 +9,8 @@
 
 namespace Ice
 {
-    /// Base class for marshaled result structures, which are generated for operations having the marshaled-result
-    /// metadata tag.
+    /// Base class for marshaled result structures, which are generated for operations marked with
+    /// "marshaled-result" metadata.
     /// @headerfile Ice/Ice.h
     class ICE_API MarshaledResult
     {

cpp/include/Ice/ObjectAdapter.h

@@ -180,7 +180,7 @@ namespace Ice
         /// @throws NotRegisteredException Thrown when no servant with the given identity and facet is registered.
         virtual ObjectPtr removeFacet(const Identity& id, std::string_view facet) = 0;
 
-        /// Removes all facets with the given identity from the Active Servant Map. The function completely removes the
+        /// Removes all facets with the given identity from the Active Servant Map. This function completely removes the
         /// Ice object, including its default facet.
         /// @param id The identity of the Ice object to be removed.
         /// @return A collection containing all the facet names and servants of the removed Ice object.
@@ -219,6 +219,8 @@ namespace Ice
         /// @param proxy The proxy that provides the identity and facet to search.
         /// @return The servant that matches the identity and facet carried by @p proxy, or nullptr if no such servant
         /// has been found.
+        /// @remark This function only tries to find the servant in the ASM and among the default servants. It does not
+        /// attempt to locate a servant using servant locators.
         [[nodiscard]] virtual ObjectPtr findByProxy(const ObjectPrx& proxy) const = 0;
 
         /// Adds a ServantLocator to this object adapter for a specific category.

csharp/src/Ice/BatchRequest.cs

@@ -5,30 +5,31 @@
 namespace Ice;
 
 /// <summary>
-/// Represents an invocation on a proxy configured for batch-oneway or batch-datagram.
+/// Represents a batch request. A batch request is created by invoking an operation on a batch-oneway or
+/// batch-datagram proxy.
 /// </summary>
 public interface BatchRequest
 {
     /// <summary>
-    /// Queues the request for an eventual flush.
+    /// Queues this request.
     /// </summary>
     void enqueue();
 
     /// <summary>
-    /// Get the marshaled size of the request.
+    /// Gets the size of the request.
     /// </summary>
-    /// <returns>The request size.</returns>
+    /// <returns>The number of bytes consumed by the request.</returns>
     int getSize();
 
     /// <summary>
     /// Gets the name of the operation.
     /// </summary>
-    /// <returns>The request operation.</returns>
+    /// <returns>The operation name.</returns>
     string getOperation();
 
     /// <summary>
-    /// The proxy used to invoke the batch request.
+    /// Gets the proxy used to create this batch request.
     /// </summary>
-    /// <returns>The request proxy.</returns>
+    /// <returns>The proxy.</returns>
     ObjectPrx getProxy();
 }

csharp/src/Ice/Communicator.cs

@@ -7,6 +7,21 @@
 
 namespace Ice;
 
+/// <summary>
+/// Communicator is the central object in Ice. Its responsibilities include:
+/// <list type="bullet">
+/// <item>creating and managing outgoing connections</item>
+/// <item>executing callbacks in its client thread pool</item>
+/// <item>creating and destroying object adapters</item>
+/// <item>loading plug-ins</item>
+/// <item>managing properties (configuration), retries, logging, instrumentation, and more.</item>
+/// </list>
+/// A Communicator is usually the first object you create when programming with Ice.
+/// You can create multiple communicators in a single program, but this is not common.
+/// </summary>
+/// <seealso cref="Logger"/>
+/// <seealso cref="ObjectAdapter"/>
+/// <seealso cref="Properties"/>
 public sealed class Communicator : IDisposable, IAsyncDisposable
 {
     /// <summary>
@@ -57,17 +72,20 @@ public Communicator(InitializationData? initData = null)
     }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="Communicator" /> class.
+    /// Initializes a new instance of the <see cref="Communicator" /> class, using Ice properties parsed from
+    /// command-line arguments. This constructor uses <paramref name="args"/> to create the <see cref="Properties"/>
+    /// of the new communicator.
     /// </summary>
-    /// <param name="args">The command-line arguments. This constructor uses <paramref name="args"/> to create
-    /// the <see cref="Properties"/> of the new communicator.</param>
+    /// <param name="args">The command-line arguments.</param>
     public Communicator(ref string[] args)
         : this(new InitializationData { properties = new Properties(ref args) })
     {
     }
 
     /// <summary>
-    /// Disposes this communicator. It's an alias for <see cref="destroy"/>.
+    /// Disposes this communicator. This method calls <see cref="shutdown" /> implicitly. Calling dispose destroys all
+    /// object adapters, and closes all outgoing connections. This method waits for all outstanding dispatches to
+    /// complete before returning. This includes "bidirectional dispatches" that execute on outgoing connections.
     /// </summary>
     public void Dispose() => destroy();
 
@@ -90,16 +108,15 @@ public ValueTask DisposeAsync()
     }
 
     /// <summary>
-    /// Destroys the communicator. This method calls <see cref="shutdown" /> implicitly. Calling destroy destroys all
-    /// object adapters, and closes all outgoing connections. This method waits for all outstanding dispatches to
-    /// complete before returning. This includes "bidirectional dispatches" that execute on outgoing connections.
+    /// Destroys this communicator. It's an alias for <see cref="Dispose"/>.
     /// </summary>
     public void destroy() => instance.destroy();
 
     /// <summary>
-    /// Shuts down this communicator: call <see cref="ObjectAdapter.deactivate"/> on all object adapters created by
-    /// this communicator. Shutting down a communicator has no effect on outgoing connections.
+    /// Shuts down this communicator. This method calls <see cref="ObjectAdapter.deactivate"/> on all object adapters
+    /// created by this communicator. Shutting down a communicator has no effect on outgoing connections.
     /// </summary>
+    /// <seealso cref="waitForShutdown" />
     public void shutdown()
     {
         try
@@ -116,7 +133,7 @@ public void shutdown()
     /// Waits for the shutdown of this communicator to complete.
     /// This method calls <see cref="ObjectAdapter.waitForDeactivate" /> on all object adapters created by this
     /// communicator. In a client application that does not accept incoming connections, this method returns as soon as
-    /// another thread calls <see cref="shutdown" /> or <see cref="destroy" /> on this communicator.
+    /// another thread calls <see cref="shutdown" /> or <see cref="Dispose" /> on this communicator.
     /// </summary>
     public void waitForShutdown()
     {
@@ -133,7 +150,8 @@ public void waitForShutdown()
     /// <summary>
     /// Checks whether or not <see cref="shutdown" /> was called on this communicator.
     /// </summary>
-    /// <returns>True if shutdown was called on this communicator; false otherwise.</returns>
+    /// <returns><see langword="true"/> if shutdown was called on this communicator;
+    /// <see langword="false"/> otherwise.</returns>
     public bool isShutdown()
     {
         try
@@ -148,13 +166,10 @@ public bool isShutdown()
 
     /// <summary>
     /// Converts a stringified proxy into a proxy.
-    /// For example, "MyCategory/MyObject:tcp -h some_host -p 10000" creates a proxy that refers to the Ice object
-    /// having an identity with a name "MyObject" and a category "MyCategory", with the server running on host
-    /// "some_host", port 10000. If the stringified proxy does not parse correctly, this method throws ParseException.
-    /// Refer to the Ice manual for a detailed description of the syntax supported by stringified proxies.
     /// </summary>
     /// <param name="str">The stringified proxy to convert into a proxy.</param>
-    /// <returns>The proxy, or null if str is an empty string.</returns>
+    /// <returns>The proxy, or null if <paramref name="str" /> is an empty string.</returns>
+    /// <exception cref="ParseException">Thrown when <paramref name="str" /> is not a valid proxy string.</exception>
     public ObjectPrx? stringToProxy(string str)
     {
         Reference? reference = instance.referenceFactory().create(str, "");
@@ -174,7 +189,6 @@ public string proxyToString(ObjectPrx? proxy) =>
     /// argument refers to a property containing a stringified proxy, such as `MyProxy=id:tcp -h localhost -p 10000`.
     /// Additional properties configure local settings for the proxy.
     /// </summary>
-    ///
     /// <param name="property">The base property name.</param>
     /// <returns>The proxy, or <c>null</c> if the property is not set.</returns>
     public ObjectPrx? propertyToProxy(string property)
@@ -185,7 +199,7 @@ public string proxyToString(ObjectPrx? proxy) =>
     }
 
     /// <summary>
-    /// Converts a proxy to a set of proxy properties.
+    /// Converts a proxy into a set of proxy properties.
     /// </summary>
     /// <param name="proxy">The proxy.</param>
     /// <param name="prefix">The base property name.</param>
@@ -200,34 +214,30 @@ public Dictionary<string, string> proxyToProperty(ObjectPrx proxy, string prefix
     /// <returns>The "stringified" identity.</returns>
     public string identityToString(Identity ident) => Util.identityToString(ident, instance.toStringMode());
 
-    /// <summary>Creates a new object adapter. The endpoints for the object adapter are taken from the property
-    /// name.Endpoints. It is legal to create an object adapter with the empty string as its name. Such an object
-    /// adapter is accessible via bidirectional connections or by collocated invocations that originate from the
-    /// same communicator as is used by the adapter. Attempts to create a named object adapter for which no
-    /// configuration can be found raise InitializationException.</summary>
+    /// <summary>
+    /// Creates a new object adapter. The endpoints for the object adapter are taken from the property
+    /// <c>name.Endpoints</c>.
+    /// It is legal to create an object adapter with the empty string as its name. Such an object
+    /// adapter is accessible via bidirectional connections or by collocated invocations.
+    /// </summary>
     /// <param name="name">The object adapter name.</param>
-    /// <param name="serverAuthenticationOptions">The authentication options used by the SSL transport. Pass null
-    /// if the adapter doesn't have any secure endpoints or if the SSL transport is configured using IceSSL properties.
-    /// When <paramref name="serverAuthenticationOptions"/> is set to a non-null value, all IceSSL properties are
-    /// ignored, and all the required configuration must be set using the <see cref="SslServerAuthenticationOptions"/>
-    /// object.
-    /// </param>
+    /// <param name="serverAuthenticationOptions">The SSL options for server connections.</param>
     /// <returns>The new object adapter.</returns>
+    /// <exception cref="InitializationException">Thrown when a named object adapter is created for which no
+    /// configuration can be found.</exception>
     public ObjectAdapter createObjectAdapter(
         string name,
         SslServerAuthenticationOptions? serverAuthenticationOptions = null) =>
         instance.objectAdapterFactory().createObjectAdapter(name, null, serverAuthenticationOptions);
 
-    /// <summary>Creates a new object adapter with endpoints. This method sets the property name.Endpoints, and
-    /// then calls createObjectAdapter. It is provided as a convenience function. Calling this operation with an
-    /// empty name will result in a UUID being generated for the name.</summary>
+    /// <summary>
+    /// Creates a new object adapter with endpoints. This method sets the property <c>name.Endpoints</c>,
+    /// and then calls <see cref="createObjectAdapter"/>. It is provided as a convenience method.
+    /// Calling this method with an empty name will result in a UUID being generated for the name.
+    /// </summary>
     /// <param name="name">The object adapter name.</param>
-    /// <param name="endpoints">The endpoints for the object adapter.</param>
-    /// <param name="serverAuthenticationOptions">The authentication options used by the SSL transport. Pass null
-    /// if the adapter doesn't have any secure endpoints or if the SSL transport is configured using IceSSL properties.
-    /// When <paramref name="serverAuthenticationOptions"/> is set to a non-null value, all IceSSL properties are
-    /// ignored, and all the required configuration must be set using the <see cref="SslServerAuthenticationOptions"/>
-    /// object.</param>
+    /// <param name="endpoints">The endpoints of the object adapter.</param>
+    /// <param name="serverAuthenticationOptions">The SSL options for server connections.</param>
     /// <returns>The new object adapter.</returns>
     public ObjectAdapter createObjectAdapterWithEndpoints(
         string name,
@@ -245,7 +255,7 @@ public ObjectAdapter createObjectAdapterWithEndpoints(
 
     /// <summary>
     /// Creates a new object adapter with a router.
-    /// This method creates a routed object adapter. Calling this operation with an empty name will result in a UUID
+    /// This method creates a routed object adapter. Calling this method with an empty name will result in a UUID
     /// being generated for the name.
     /// </summary>
     /// <param name="name">The object adapter name.</param>

csharp/src/Ice/CompositeSliceLoader.cs

@@ -4,16 +4,22 @@
 
 namespace Ice;
 
-/// <summary>Implements <see cref="SliceLoader" /> by combining multiple Slice loaders.</summary>
+/// <summary>
+/// Implements <see cref="SliceLoader" /> by combining multiple SliceLoader instances.
+/// </summary>
 public sealed class CompositeSliceLoader : SliceLoader
 {
     private readonly List<SliceLoader> _loaders;
 
-    /// <summary>Initializes a new instance of the <see cref="CompositeSliceLoader" /> class.</summary>
-    /// <param name="loaders">The initial Slice loaders to combine.</param>
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CompositeSliceLoader" /> class.
+    /// </summary>
+    /// <param name="loaders">The initial Slice loaders to use.</param>
     public CompositeSliceLoader(params SliceLoader[] loaders) => _loaders = new List<SliceLoader>(loaders);
 
-    /// <summary>Adds a <see cref="SliceLoader" /> to this <see cref="CompositeSliceLoader" />.</summary>
+    /// <summary>
+    /// Adds a <see cref="SliceLoader" /> instance to this <see cref="CompositeSliceLoader" />.
+    /// </summary>
     /// <param name="loader">The Slice loader to add.</param>
     public void add(SliceLoader loader) => _loaders.Add(loader);