[api-docs] Even more documentation

This PR fleshes out more of the documentation labeled as TBD.

src/contrib/cluster/Akka.Cluster.Sharding/ClusterSharding.cs

@@ -291,6 +291,9 @@ public static Config DefaultConfig()
         /// The message that will be sent to entities when they are to be stopped for a rebalance or 
         /// graceful shutdown of a <see cref="Sharding.ShardRegion"/>, e.g. <see cref="PoisonPill"/>.
         /// </param>
+        /// <exception cref="IllegalStateException">
+        /// This exception is thrown when the cluster member doesn't have the role specified in <paramref name="settings"/>.
+        /// </exception>
         /// <returns>The actor ref of the <see cref="Sharding.ShardRegion"/> that is to be responsible for the shard.</returns>
         public IActorRef Start(
             string typeName, //TODO: change type name to type instance?
@@ -335,6 +338,9 @@ public IActorRef Start(
         /// The message that will be sent to entities when they are to be stopped for a rebalance or 
         /// graceful shutdown of a <see cref="Sharding.ShardRegion"/>, e.g. <see cref="PoisonPill"/>.
         /// </param>
+        /// <exception cref="IllegalStateException">
+        /// This exception is thrown when the cluster member doesn't have the role specified in <paramref name="settings"/>.
+        /// </exception>
         /// <returns>The actor ref of the <see cref="Sharding.ShardRegion"/> that is to be responsible for the shard.</returns>
         public async Task<IActorRef> StartAsync(
             string typeName, //TODO: change type name to type instance?

src/contrib/cluster/Akka.Cluster.Sharding/ClusterShardingGuardian.cs

@@ -85,12 +85,14 @@ public sealed class Start : INoSerializationVerificationNeeded
             /// <param name="shardResolver">TBD</param>
             /// <param name="allocationStrategy">TBD</param>
             /// <param name="handOffStopMessage">TBD</param>
-            /// <exception cref="ArgumentNullException">TBD</exception>
+            /// <exception cref="ArgumentNullException">
+            /// This exception is thrown when the specified <paramref name="typeName"/> or <paramref name="entityProps"/> is undefined.
+            /// </exception>
             public Start(string typeName, Props entityProps, ClusterShardingSettings settings,
                 IdExtractor idIdExtractor, ShardResolver shardResolver, IShardAllocationStrategy allocationStrategy, object handOffStopMessage)
             {
-                if (string.IsNullOrEmpty(typeName)) throw new ArgumentNullException("typeName", "ClusterSharding start requires type name to be provided");
-                if (entityProps == null) throw new ArgumentNullException("entityProps", string.Format("ClusterSharding start requires Props for [{0}] to be provided", typeName));
+                if (string.IsNullOrEmpty(typeName)) throw new ArgumentNullException(nameof(typeName), "ClusterSharding start requires type name to be provided");
+                if (entityProps == null) throw new ArgumentNullException(nameof(entityProps), $"ClusterSharding start requires Props for [{typeName}] to be provided");
 
                 TypeName = typeName;
                 EntityProps = entityProps;
@@ -132,10 +134,12 @@ public sealed class StartProxy : INoSerializationVerificationNeeded
             /// <param name="settings">TBD</param>
             /// <param name="extractEntityId">TBD</param>
             /// <param name="extractShardId">TBD</param>
-            /// <exception cref="ArgumentException">TBD</exception>
+            /// <exception cref="ArgumentException">
+            /// This exception is thrown when the specified <paramref name="typeName"/> is undefined.
+            /// </exception>
             public StartProxy(string typeName, ClusterShardingSettings settings, IdExtractor extractEntityId, ShardResolver extractShardId)
             {
-                if (string.IsNullOrEmpty(typeName)) throw new ArgumentNullException("typeName", "ClusterSharding start proxy requires type name to be provided");
+                if (string.IsNullOrEmpty(typeName)) throw new ArgumentNullException(nameof(typeName), "ClusterSharding start proxy requires type name to be provided");
 
                 TypeName = typeName;
                 Settings = settings;

src/contrib/cluster/Akka.Cluster.Sharding/ClusterShardingSettings.cs

@@ -80,6 +80,10 @@ public class TunningParameters
         /// <param name="snapshotAfter">TBD</param>
         /// <param name="leastShardAllocationRebalanceThreshold">TBD</param>
         /// <param name="leastShardAllocationMaxSimultaneousRebalance">TBD</param>
+        /// <exception cref="ArgumentException">
+        /// This exception is thrown when the specified <paramref name="entityRecoveryStrategy"/> is invalid.
+        /// Acceptable values include: all | constant
+        /// </exception>
         public TunningParameters(
             TimeSpan coordinatorFailureBackoff,
             TimeSpan retryInterval,
@@ -283,12 +287,14 @@ public ClusterShardingSettings WithSnapshotPluginId(string snapshotPluginId)
         /// TBD
         /// </summary>
         /// <param name="tunningParameters">TBD</param>
-        /// <exception cref="ArgumentException">TBD</exception>
+        /// <exception cref="ArgumentNullException">
+        /// This exception is thrown when the specified <paramref name="tunningParameters"/> is undefined.
+        /// </exception>
         /// <returns>TBD</returns>
         public ClusterShardingSettings WithTuningParameters(TunningParameters tunningParameters)
         {
             if (tunningParameters == null)
-                throw new ArgumentNullException("tunningParameters");
+                throw new ArgumentNullException(nameof(tunningParameters), $"ClusterShardingSettings requires {nameof(tunningParameters)} to be provided");
 
             return Copy(tunningParameters: tunningParameters);
         }
@@ -297,11 +303,14 @@ public ClusterShardingSettings WithTuningParameters(TunningParameters tunningPar
         /// TBD
         /// </summary>
         /// <param name="coordinatorSingletonSettings">TBD</param>
+        /// <exception cref="ArgumentNullException">
+        /// This exception is thrown when the specified <paramref name="coordinatorSingletonSettings"/> is undefined.
+        /// </exception>
         /// <returns>TBD</returns>
         public ClusterShardingSettings WithCoordinatorSingletonSettings(ClusterSingletonManagerSettings coordinatorSingletonSettings)
         {
             if (coordinatorSingletonSettings == null)
-                throw new ArgumentNullException("coordinatorSingletonSettings");
+                throw new ArgumentNullException(nameof(coordinatorSingletonSettings), $"ClusterShardingSettings requires {nameof(coordinatorSingletonSettings)} to be provided");
 
             return Copy(coordinatorSingletonSettings: coordinatorSingletonSettings);
         }
@@ -323,4 +332,4 @@ private ClusterShardingSettings Copy(
                 coordinatorSingletonSettings: coordinatorSingletonSettings ?? CoordinatorSingletonSettings);
         }
     }
-}
+}

src/contrib/cluster/Akka.Cluster.Sharding/PersistentShardCoordinator.cs

@@ -28,7 +28,7 @@ public partial class PersistentShardCoordinator : PersistentActor
         /// Persistent state of the event sourced PersistentShardCoordinator.
         /// </summary>
         [Serializable]
-        internal protected sealed class State
+        protected internal sealed class State
         {
             /// <summary>
             /// TBD
@@ -90,23 +90,22 @@ public State Updated(IDomainEvent e)
                 if (e is ShardRegionRegistered)
                 {
                     var message = e as ShardRegionRegistered;
-                    if (Regions.ContainsKey(message.Region)) throw new ArgumentException($"Region {message.Region} is already registered");
+                    if (Regions.ContainsKey(message.Region)) throw new ArgumentException($"Region {message.Region} is already registered", nameof(e));
 
                     return Copy(regions: Regions.SetItem(message.Region, ImmutableList<ShardId>.Empty));
                 }
                 else if (e is ShardRegionProxyRegistered)
                 {
                     var message = e as ShardRegionProxyRegistered;
-                    if (RegionProxies.Contains(message.RegionProxy)) throw new ArgumentException($"Region proxy {message.RegionProxy} is already registered");
+                    if (RegionProxies.Contains(message.RegionProxy)) throw new ArgumentException($"Region proxy {message.RegionProxy} is already registered", nameof(e));
 
                     return Copy(regionProxies: RegionProxies.Add(message.RegionProxy));
                 }
                 else if (e is ShardRegionTerminated)
                 {
                     IImmutableList<ShardId> shardRegions;
                     var message = e as ShardRegionTerminated;
-                    if (!Regions.TryGetValue(message.Region, out shardRegions)) throw new ArgumentException(
-                        $"Region {message.Region} not registered");
+                    if (!Regions.TryGetValue(message.Region, out shardRegions)) throw new ArgumentException($"Region {message.Region} not registered", nameof(e));
 
                     return Copy(
                         regions: Regions.Remove(message.Region),
@@ -116,16 +115,16 @@ public State Updated(IDomainEvent e)
                 else if (e is ShardRegionProxyTerminated)
                 {
                     var message = e as ShardRegionProxyTerminated;
-                    if (!RegionProxies.Contains(message.RegionProxy)) throw new ArgumentException($"Region proxy {message.RegionProxy} not registered");
+                    if (!RegionProxies.Contains(message.RegionProxy)) throw new ArgumentException($"Region proxy {message.RegionProxy} not registered", nameof(e));
 
                     return Copy(regionProxies: RegionProxies.Remove(message.RegionProxy));
                 }
                 else if (e is ShardHomeAllocated)
                 {
                     IImmutableList<ShardId> shardRegions;
                     var message = e as ShardHomeAllocated;
-                    if (!Regions.TryGetValue(message.Region, out shardRegions)) throw new ArgumentException($"Region {message.Region} not registered");
-                    if (Shards.ContainsKey(message.Shard)) throw new ArgumentException($"Shard {message.Shard} is already allocated");
+                    if (!Regions.TryGetValue(message.Region, out shardRegions)) throw new ArgumentException($"Region {message.Region} not registered", nameof(e));
+                    if (Shards.ContainsKey(message.Shard)) throw new ArgumentException($"Shard {message.Shard} is already allocated", nameof(e));
 
                     return Copy(
                         shards: Shards.SetItem(message.Shard, message.Region),
@@ -137,8 +136,8 @@ public State Updated(IDomainEvent e)
                     IActorRef region;
                     IImmutableList<ShardId> shardRegions;
                     var message = e as ShardHomeDeallocated;
-                    if (!Shards.TryGetValue(message.Shard, out region)) throw new ArgumentException($"Shard {message.Shard} not allocated");
-                    if (!Regions.TryGetValue(region, out shardRegions)) throw new ArgumentException($"Region {region} for shard {message.Shard} not registered");
+                    if (!Shards.TryGetValue(message.Shard, out region)) throw new ArgumentException($"Shard {message.Shard} not allocated", nameof(e));
+                    if (!Regions.TryGetValue(region, out shardRegions)) throw new ArgumentException($"Region {region} for shard {message.Shard} not registered", nameof(e));
 
                     return Copy(
                         shards: Shards.Remove(message.Shard),

src/contrib/cluster/Akka.Cluster.Sharding/Shard.cs

@@ -40,7 +40,7 @@ public interface IShardQuery { }
         /// When a <see cref="StateChange"/> fails to write to the journal, we will retry it after a back off.
         /// </summary>
         [Serializable]
-        internal protected class RetryPersistence : IShardCommand
+        protected internal class RetryPersistence : IShardCommand
         {
             /// <summary>
             /// TBD
@@ -61,7 +61,7 @@ public RetryPersistence(StateChange payload)
         /// The Snapshot tick for the shards.
         /// </summary>
         [Serializable]
-        internal protected sealed class SnapshotTick : IShardCommand
+        protected internal sealed class SnapshotTick : IShardCommand
         {
             /// <summary>
             /// TBD
@@ -78,7 +78,7 @@ private SnapshotTick()
         /// we restart it after a back off using this message.
         /// </summary>
         [Serializable]
-        internal protected sealed class RestartEntity : IShardCommand
+        protected internal sealed class RestartEntity : IShardCommand
         {
             /// <summary>
             /// TBD
@@ -117,7 +117,10 @@ public RestartEntities(IImmutableSet<EntityId> entries)
             }
         }
 
-        internal protected abstract class StateChange
+        /// <summary>
+        /// TBD
+        /// </summary>
+        protected internal abstract class StateChange
         {
             /// <summary>
             /// TBD
@@ -135,11 +138,7 @@ protected StateChange(EntityId entityId)
 
             #region Equals
 
-            /// <summary>
-            /// TBD
-            /// </summary>
-            /// <param name="obj">TBD</param>
-            /// <returns>TBD</returns>
+            /// <inheritdoc/>
             public override bool Equals(object obj)
             {
                 var other = obj as StateChange;
@@ -150,10 +149,7 @@ public override bool Equals(object obj)
                 return EntityId.Equals(other.EntityId);
             }
 
-            /// <summary>
-            /// TBD
-            /// </summary>
-            /// <returns>TBD</returns>
+            /// <inheritdoc/>
             public override int GetHashCode()
             {
                 unchecked
@@ -169,7 +165,7 @@ public override int GetHashCode()
         /// <see cref="ShardState"/> change for starting an entity in this `Shard`
         /// </summary>
         [Serializable]
-        internal protected sealed class EntityStarted : StateChange
+        protected internal sealed class EntityStarted : StateChange
         {
             /// <summary>
             /// TBD
@@ -184,7 +180,7 @@ public EntityStarted(string entityId) : base(entityId)
         /// <see cref="ShardState"/> change for an entity which has terminated.
         /// </summary>
         [Serializable]
-        internal protected sealed class EntityStopped : StateChange
+        protected internal sealed class EntityStopped : StateChange
         {
             /// <summary>
             /// TBD
@@ -282,11 +278,7 @@ public ShardStats(string shardId, int entityCount)
 
             #region Equals
 
-            /// <summary>
-            /// TBD
-            /// </summary>
-            /// <param name="obj">TBD</param>
-            /// <returns>TBD</returns>
+            /// <inheritdoc/>
             public override bool Equals(object obj)
             {
                 var other = obj as ShardStats;
@@ -298,10 +290,7 @@ public override bool Equals(object obj)
                     && EntityCount.Equals(other.EntityCount);
             }
 
-            /// <summary>
-            /// TBD
-            /// </summary>
-            /// <returns>TBD</returns>
+            /// <inheritdoc/>
             public override int GetHashCode()
             {
                 unchecked
@@ -321,7 +310,7 @@ public override int GetHashCode()
         /// Persistent state of the Shard.
         /// </summary>
         [Serializable]
-        internal protected class ShardState : IClusterShardingSerializable
+        protected internal class ShardState : IClusterShardingSerializable
         {
             /// <summary>
             /// TBD
@@ -344,11 +333,7 @@ public ShardState(IImmutableSet<EntityId> entries)
 
             #region Equals
 
-            /// <summary>
-            /// TBD
-            /// </summary>
-            /// <param name="obj">TBD</param>
-            /// <returns>TBD</returns>
+            /// <inheritdoc/>
             public override bool Equals(object obj)
             {
                 var other = obj as ShardState;
@@ -359,10 +344,7 @@ public override bool Equals(object obj)
                 return Entries.SequenceEqual(other.Entries);
             }
 
-            /// <summary>
-            /// TBD
-            /// </summary>
-            /// <returns>TBD</returns>
+            /// <inheritdoc/>
             public override int GetHashCode()
             {
                 unchecked

src/contrib/dependencyinjection/Akka.DI.Core/DIActorContextAdapter.cs

@@ -24,11 +24,11 @@ public class DIActorContextAdapter
         /// </summary>
         /// <param name="context">The actor context associated with a system that contains the DI extension.</param>
         /// <exception cref="ArgumentNullException">
-        /// The <paramref name="context"/> was null.
+        /// This exception is thrown when the specified <paramref name="context"/> is undefined.
         /// </exception>
         public DIActorContextAdapter(IActorContext context)
         {
-            if (context == null) throw new ArgumentNullException("context");
+            if (context == null) throw new ArgumentNullException(nameof(context), $"DIAcotrContextAdapter requires {nameof(context)} to be provided");
             this.context = context;
             this.producer = context.System.GetExtension<DIExt>();
         }

src/contrib/dependencyinjection/Akka.DI.Core/DIActorProducer.cs

@@ -26,12 +26,12 @@ public class DIActorProducer : IIndirectActorProducer
         /// <param name="dependencyResolver">The resolver used to resolve the given actor type.</param>
         /// <param name="actorType">The type of actor that this producer creates.</param>
         /// <exception cref="ArgumentNullException">
-        /// Either the <paramref name="dependencyResolver"/> or the <paramref name="actorType"/> was null.
+        /// This exception is thrown when either the specified <paramref name="dependencyResolver"/> or the specified <paramref name="actorType"/> is undefined.
         /// </exception>
         public DIActorProducer(IDependencyResolver dependencyResolver, Type actorType)
         {
-            if (dependencyResolver == null) throw new ArgumentNullException("dependencyResolver");
-            if (actorType == null) throw new ArgumentNullException("actorType");
+            if (dependencyResolver == null) throw new ArgumentNullException(nameof(dependencyResolver), $"DIActorProducer requires {nameof(dependencyResolver)} to be provided");
+            if (actorType == null) throw new ArgumentNullException(nameof(actorType), $"DIActorProducer requires {nameof(actorType)} to be provided");
 
             this.dependencyResolver = dependencyResolver;
             this.actorType = actorType;

src/contrib/dependencyinjection/Akka.DI.Core/DIActorSystemAdapter.cs

@@ -24,11 +24,11 @@ public class DIActorSystemAdapter
         /// </summary>
         /// <param name="system">The actor system that contains the DI extension.</param>
         /// <exception cref="ArgumentNullException">
-        /// The <paramref name="system"/> was null.
+        /// This exception is thrown when the specified <paramref name="system"/> is undefined.
         /// </exception>
         public DIActorSystemAdapter(ActorSystem system)
         {
-            if (system == null) throw new ArgumentNullException("system");
+            if (system == null) throw new ArgumentNullException(nameof(system), $"DIActorSystemAdapter requires {nameof(system)} to be provided");
             this.system = system;
             this.producer = system.GetExtension<DIExt>();
         }