[api-docs] More documentation (#2567)

This PR fleshes out more of the documentation labeled as TBD. It also corrects a few incorrect copyright headers and adds few more missing documentation tags.
akkadotnet · Mar 27, 2017 · 34c0e22 · 34c0e22
1 parent 69baba6
commit 34c0e22
Show file tree

Hide file tree

Showing 40 changed files with 372 additions and 217 deletions.
diff --git a/src/contrib/cluster/Akka.Cluster.Sharding.Tests/AllAtOnceEntityRecoveryStrategySpec.cs b/src/contrib/cluster/Akka.Cluster.Sharding.Tests/AllAtOnceEntityRecoveryStrategySpec.cs
@@ -1,5 +1,5 @@
 //-----------------------------------------------------------------------
-// <copyright file="PersistentShard.cs" company="Akka.NET Project">
+// <copyright file="AllAtOnceEntityRecoveryStrategySpec.cs" company="Akka.NET Project">
 //     Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
 //     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
 // </copyright>

diff --git a/src/contrib/cluster/Akka.Cluster.Sharding.Tests/ConstantRateEntityRecoveryStrategySpec.cs b/src/contrib/cluster/Akka.Cluster.Sharding.Tests/ConstantRateEntityRecoveryStrategySpec.cs
@@ -1,5 +1,5 @@
 //-----------------------------------------------------------------------
-// <copyright file="PersistentShard.cs" company="Akka.NET Project">
+// <copyright file="ConstantRateEntityRecoveryStrategySpec.cs" company="Akka.NET Project">
 //     Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
 //     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
 // </copyright>

diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/ClusterSharding.cs b/src/contrib/cluster/Akka.Cluster.Sharding/ClusterSharding.cs
@@ -661,14 +661,15 @@ public IActorRef ShardRegion(string typeName)
             {
                 return region;
             }
-            throw new ArgumentException(string.Format("Shard type [{0}] must be started first", typeName));
+            throw new ArgumentException($"Shard type [{typeName}] must be started first");
         }
 
         private void RequireClusterRole(string role)
         {
             if (!(string.IsNullOrEmpty(role) || _cluster.SelfRoles.Contains(role)))
             {
-                throw new IllegalStateException(string.Format("This cluster member [{0}] doesn't have the role [{1}]", _cluster.SelfAddress, role));
+                throw new IllegalStateException(
+                    $"This cluster member [{_cluster.SelfAddress}] doesn't have the role [{role}]");
             }
         }
     }

diff --git a/src/contrib/cluster/Akka.Cluster.Sharding/EntityRecoveryStrategy.cs b/src/contrib/cluster/Akka.Cluster.Sharding/EntityRecoveryStrategy.cs
@@ -1,5 +1,5 @@
 //-----------------------------------------------------------------------
-// <copyright file="PersistentShard.cs" company="Akka.NET Project">
+// <copyright file="EntityRecoveryStrategy.cs" company="Akka.NET Project">
 //     Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
 //     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
 // </copyright>

diff --git a/.../cluster/Akka.Cluster.Tools.Tests.MultiNode/ClusterClient/ClusterClientStartSpecConfig.cs b/.../cluster/Akka.Cluster.Tools.Tests.MultiNode/ClusterClient/ClusterClientStartSpecConfig.cs
@@ -1,11 +1,16 @@
-using System.Collections.Generic;
+//-----------------------------------------------------------------------
+// <copyright file="ClusterClientStartSpecConfig.cs" company="Akka.NET Project">
+//     Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
+//     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
+// </copyright>
+//-----------------------------------------------------------------------
+
 using System.Collections.Immutable;
 using System.Linq;
 using Akka.Actor;
 using Akka.Cluster.TestKit;
 using Akka.Cluster.Tools.Client;
 using Akka.Cluster.Tools.PublishSubscribe;
-using Akka.Cluster.Tools.PublishSubscribe.Internal;
 using Akka.Configuration;
 using Akka.Remote.TestKit;
 using FluentAssertions;

diff --git a/src/contrib/persistence/Akka.Persistence.Sql.TestKit/SqlJournalConnectionFailureSpec.cs b/src/contrib/persistence/Akka.Persistence.Sql.TestKit/SqlJournalConnectionFailureSpec.cs
@@ -1,9 +1,12 @@
-using System;
+//-----------------------------------------------------------------------
+// <copyright file="SqlJournalConnectionFailureSpec.cs" company="Akka.NET Project">
+//     Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
+//     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
+// </copyright>
+//-----------------------------------------------------------------------
+
+using System;
 using System.Collections.Generic;
-using System.Data.Common;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 using Akka.Actor;
 using Akka.Configuration;
 using Xunit;

diff --git a/src/contrib/persistence/Akka.Persistence.Sql.TestKit/SqlSnapshotConnectionFailureSpec.cs b/src/contrib/persistence/Akka.Persistence.Sql.TestKit/SqlSnapshotConnectionFailureSpec.cs
@@ -1,11 +1,15 @@
-using System;
+//-----------------------------------------------------------------------
+// <copyright file="SqlSnapshotConnectionFailureSpec.cs" company="Akka.NET Project">
+//     Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
+//     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
+// </copyright>
+//-----------------------------------------------------------------------
+
+using System;
 using System.Collections.Generic;
 using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 using Akka.Actor;
 using Akka.Configuration;
-using FluentAssertions;
 using Xunit;
 using Xunit.Abstractions;
 

diff --git a/src/contrib/persistence/Akka.Persistence.Sqlite.Tests/SqliteJournalConnectionFailureSpec.cs b/src/contrib/persistence/Akka.Persistence.Sqlite.Tests/SqliteJournalConnectionFailureSpec.cs
@@ -1,11 +1,12 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
+//-----------------------------------------------------------------------
+// <copyright file="SqliteJournalConnectionFailureSpec.cs" company="Akka.NET Project">
+//     Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
+//     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
+// </copyright>
+//-----------------------------------------------------------------------
+
 using Akka.Configuration;
 using Akka.Persistence.Sql.TestKit;
-using Akka.Util.Internal;
 using Xunit.Abstractions;
 
 namespace Akka.Persistence.Sqlite.Tests

diff --git a/...rib/persistence/Akka.Persistence.Sqlite.Tests/SqliteSnapshotStoreConnectionFailureSpec.cs b/...rib/persistence/Akka.Persistence.Sqlite.Tests/SqliteSnapshotStoreConnectionFailureSpec.cs
@@ -1,11 +1,12 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
+//-----------------------------------------------------------------------
+// <copyright file="SqliteSnapshotStoreConnectionFailureSpec.cs" company="Akka.NET Project">
+//     Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
+//     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
+// </copyright>
+//-----------------------------------------------------------------------
+
 using Akka.Configuration;
 using Akka.Persistence.Sql.TestKit;
-using Akka.Util.Internal;
 using Xunit.Abstractions;
 
 namespace Akka.Persistence.Sqlite.Tests

diff --git a/src/contrib/serializers/Akka.Serialization.Hyperion/IKnownTypesProvider.cs b/src/contrib/serializers/Akka.Serialization.Hyperion/IKnownTypesProvider.cs
@@ -1,5 +1,5 @@
 //-----------------------------------------------------------------------
-// <copyright file="HyperionSerializer.cs" company="Akka.NET Project">
+// <copyright file="IKnownTypesProvider.cs" company="Akka.NET Project">
 //     Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
 //     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
 // </copyright>

diff --git a/src/contrib/transports/Akka.Remote.Transport.Helios/Properties/AssemblyInfo.cs b/src/contrib/transports/Akka.Remote.Transport.Helios/Properties/AssemblyInfo.cs
@@ -1,5 +1,13 @@
-using System.Reflection;
-using System.Runtime.CompilerServices;
+#region copyright
+// -----------------------------------------------------------------------
+//  <copyright file="AssemblyInfo.cs" company="Akka.NET project">
+//      Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
+//      Copyright (C) 2013-2017 Akka.NET project <https://github.com/akkadotnet>
+//  </copyright>
+// -----------------------------------------------------------------------
+#endregion
+
+using System.Reflection;
 using System.Runtime.InteropServices;
 
 // General Information about an assembly is controlled through the following 

diff --git a/src/core/Akka.API.Tests/CoreAPISpec.ApproveCluster.approved.txt b/src/core/Akka.API.Tests/CoreAPISpec.ApproveCluster.approved.txt
@@ -286,7 +286,7 @@ namespace Akka.Cluster.Routing
         public override bool IsManagementMessage(object message) { }
         public override Akka.Actor.Props RoutingLogicController(Akka.Routing.RoutingLogic routingLogic) { }
         public override Akka.Util.ISurrogate ToSurrogate(Akka.Actor.ActorSystem system) { }
-        public override Akka.Routing.RouterConfig WithFallback(Akka.Routing.RouterConfig other) { }
+        public override Akka.Routing.RouterConfig WithFallback(Akka.Routing.RouterConfig routerConfig) { }
     }
     public sealed class ClusterRouterGroupSettings : Akka.Cluster.Routing.ClusterRouterSettingsBase
     {

diff --git a/src/core/Akka.API.Tests/CoreAPISpec.ApproveRemote.approved.txt b/src/core/Akka.API.Tests/CoreAPISpec.ApproveRemote.approved.txt
@@ -74,7 +74,7 @@ namespace Akka.Remote
             "nstead. [1.1.2]")]
         public DeadlineFailureDetector(System.TimeSpan acceptableHeartbeatPause, Akka.Remote.Clock clock = null) { }
         public DeadlineFailureDetector(System.TimeSpan acceptableHeartbeatPause, System.TimeSpan heartbeatInterval, Akka.Remote.Clock clock = null) { }
-        public DeadlineFailureDetector(Akka.Configuration.Config config, Akka.Event.EventStream ev) { }
+        public DeadlineFailureDetector(Akka.Configuration.Config config, Akka.Event.EventStream eventStream) { }
         public override bool IsAvailable { get; }
         public override bool IsMonitoring { get; }
         public override void HeartBeat() { }

diff --git a/src/core/Akka.Cluster.Tests/ActorRefProvidersConfigSpec.cs b/src/core/Akka.Cluster.Tests/ActorRefProvidersConfigSpec.cs
@@ -1,4 +1,11 @@
-using System;
+//-----------------------------------------------------------------------
+// <copyright file="ActorRefProvidersConfigSpec.cs" company="Akka.NET Project">
+//     Copyright (C) 2009-2016 Lightbend Inc. <http://www.lightbend.com>
+//     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
+// </copyright>
+//-----------------------------------------------------------------------
+
+using System;
 using Akka.Actor;
 using Akka.Configuration;
 using Akka.Remote;

diff --git a/src/core/Akka.Cluster/Gossip.cs b/src/core/Akka.Cluster/Gossip.cs
@@ -122,6 +122,7 @@ public Gossip(ImmutableSortedSet<Member> members, GossipOverview overview) : thi
         /// <param name="members">TBD</param>
         /// <param name="overview">TBD</param>
         /// <param name="version">TBD</param>
+        /// <exception cref="ArgumentException">TBD</exception>
         public Gossip(ImmutableSortedSet<Member> members, GossipOverview overview, VectorClock version)
         {
             _members = members;
@@ -156,19 +157,24 @@ public Gossip Copy(ImmutableSortedSet<Member> members = null, GossipOverview ove
         private void AssertInvariants()
         {
             if (_members.Any(m => m.Status == MemberStatus.Removed))
-                throw new ArgumentException(string.Format("Live members must not have status [Removed], got {0}",
-                    _members.Where(m => m.Status == MemberStatus.Removed).Select(m => m.ToString()).Aggregate((a, b) => a + ", " + b)));
+            {
+                var members = string.Join(", ", _members.Where(m => m.Status == MemberStatus.Removed).Select(m => m.ToString()));
+                throw new ArgumentException($"Live members must not have status [Removed], got {members}", nameof(_members));
+            }
 
-            var inReachabilityButNotMember =
-                _overview.Reachability.AllObservers.Except(_members.Select(m => m.UniqueAddress));
+            var inReachabilityButNotMember = _overview.Reachability.AllObservers.Except(_members.Select(m => m.UniqueAddress));
             if (!inReachabilityButNotMember.IsEmpty)
-                throw new ArgumentException("Nodes not part of cluster in reachability table, got {0}",
-                    inReachabilityButNotMember.Select(a => a.ToString()).Aggregate((a, b) => a + ", " + b));
+            {
+                var inreachability = string.Join(", ", inReachabilityButNotMember.Select(a => a.ToString()));
+                throw new ArgumentException($"Nodes not part of cluster in reachability table, got {inreachability}", nameof(_overview));
+            }
 
             var seenButNotMember = _overview.Seen.Except(_members.Select(m => m.UniqueAddress));
             if (!seenButNotMember.IsEmpty)
-                throw new ArgumentException("Nodes not part of cluster have marked the Gossip as seen, got {0}",
-                    seenButNotMember.Select(a => a.ToString()).Aggregate((a, b) => a + ", " + b));
+            {
+                var seen = string.Join(", ", seenButNotMember.Select(a => a.ToString()));
+                throw new ArgumentException($"Nodes not part of cluster have marked the Gossip as seen, got {seen}", nameof(_overview));
+            }
         }
 
         //TODO: Serializer should ignore

diff --git a/src/core/Akka.Cluster/Proto/ClusterMessageSerializer.cs b/src/core/Akka.Cluster/Proto/ClusterMessageSerializer.cs
@@ -31,11 +31,18 @@ public ClusterMessageSerializer(ExtendedActorSystem system)
 
         private const int BufferSize = 1024 * 4;
 
+        /// <summary>
+        /// Completely unique value to identify this implementation of Serializer, used to optimize network traffic
+        /// Values from 0 to 16 is reserved for Akka internal usage
+        /// </summary>
         public override int Identifier
         {
             get { return 5; }
         }
 
+        /// <summary>
+        /// Returns whether this serializer needs a manifest in the fromBinary method
+        /// </summary>
         public override bool IncludeManifest
         {
             get { return true; }
@@ -44,6 +51,14 @@ public override bool IncludeManifest
         //must be lazy because serializer is initialized from Cluster extension constructor
         private Lazy<TimeSpan> _gossipTimeToLive;
 
+        /// <summary>
+        /// Serializes the given object into a byte array
+        /// </summary>
+        /// <param name="obj">The object to serialize</param>
+        /// <exception cref="ArgumentException">
+        /// This exception is thrown when the specified object is not a cluster message.
+        /// </exception>
+        /// <returns>A byte array containing the serialized object</returns>
         public override byte[] ToBinary(object obj)
         {
             if (obj is ClusterHeartbeatSender.Heartbeat) return AddressToProtoByteArray(((ClusterHeartbeatSender.Heartbeat)obj).From);
@@ -66,9 +81,18 @@ public override byte[] ToBinary(object obj)
             if (obj is InternalClusterAction.InitJoinAck) return AddressToProtoByteArray(((InternalClusterAction.InitJoinAck)obj).Address);
             if (obj is InternalClusterAction.InitJoinNack) return AddressToProtoByteArray(((InternalClusterAction.InitJoinNack)obj).Address);
             if(obj is InternalClusterAction.ExitingConfirmed) return UniqueAddressToProtoByteArray(((InternalClusterAction.ExitingConfirmed)obj).Address);
-            throw new ArgumentException(string.Format("Can't serialize object of type {0}", obj.GetType()));
+            throw new ArgumentException($"Can't serialize object of type {obj.GetType()}", nameof(obj));
         }
 
+        /// <summary>
+        /// Deserializes a byte array into an object of type <paramref name="type" />.
+        /// </summary>
+        /// <param name="bytes">The array containing the serialized object</param>
+        /// <param name="type">The type of object contained in the array</param>
+        /// <exception cref="ArgumentException">
+        /// This exception is thrown when the specified type is not a cluster message.
+        /// </exception>
+        /// <returns>The object contained in the array</returns>
         public override object FromBinary(byte[] bytes, Type type)
         {
             if (type == typeof (InternalClusterAction.Join))
@@ -91,16 +115,18 @@ public override object FromBinary(byte[] bytes, Type type)
             if (type == typeof(InternalClusterAction.InitJoinNack)) return new InternalClusterAction.InitJoinNack(AddressFromBinary(bytes));
             if (type == typeof(ClusterHeartbeatSender.Heartbeat)) return new ClusterHeartbeatSender.Heartbeat(AddressFromBinary(bytes));
             if (type == typeof(ClusterHeartbeatSender.HeartbeatRsp)) return new ClusterHeartbeatSender.HeartbeatRsp(UniqueAddressFromBinary(bytes));
-            if(type == typeof(InternalClusterAction.ExitingConfirmed)) return new InternalClusterAction.ExitingConfirmed(UniqueAddressFromBinary(bytes));
+            if (type == typeof(InternalClusterAction.ExitingConfirmed)) return new InternalClusterAction.ExitingConfirmed(UniqueAddressFromBinary(bytes));
             if (type == typeof(GossipStatus)) return GossipStatusFromBinary(bytes);
             if (type == typeof(GossipEnvelope)) return GossipEnvelopeFromBinary(bytes);
 
-            throw new ArgumentException("Ned a cluster message class to be able to deserialize bytes in ClusterSerializer.");
+            throw new ArgumentException("Need a cluster message class to be able to deserialize bytes in ClusterSerializer.", nameof(type));
         }
 
         /// <summary>
         /// Compresses the protobuf message using GZIP compression
         /// </summary>
+        /// <param name="message">The message to compress</param>
+        /// <returns>A byte array containing the compressed message</returns>
         public byte[] Compress(IMessageLite message)
         {
             using (var bos = new MemoryStream(BufferSize))
@@ -115,6 +141,8 @@ public byte[] Compress(IMessageLite message)
         /// <summary>
         /// Decompresses the protobuf message using GZIP compression
         /// </summary>
+        /// <param name="bytes">The array containing the message to decompress</param>
+        /// <returns>A byte array containing the decompressed message</returns>
         public byte[] Decompress(byte[] bytes)
         {
             using(var input = new GZipStream(new MemoryStream(bytes), CompressionMode.Decompress))
@@ -155,7 +183,7 @@ private Address AddressFromProto(Msg.Address address)
         private Msg.Address.Builder AddressToProto(Address address)
         {
             if(string.IsNullOrEmpty(address.Host) || !address.Port.HasValue) 
-                throw new ArgumentException(string.Format("Address [{0}] could not be serialized: host or port missing.", address), "address");
+                throw new ArgumentException($"Address [{address}] could not be serialized: host or port missing.", nameof(address));
             return
                 Msg.Address.CreateBuilder()
                     .SetSystem(address.System)
@@ -260,7 +288,7 @@ private string GetSystem(Msg.Address address)
         private int MapWithErrorMessage<T>(Dictionary<T, int> map, T value, string unknown)
         {
             if (map.ContainsKey(value)) return map[value];
-            throw new ArgumentException(string.Format("Unknown {0} [{1}] in cluster message", unknown, value));
+            throw new ArgumentException($"Unknown {unknown} [{value}] in cluster message");
         }
 
         private Msg.Join JoinToProto(UniqueAddress node, ImmutableHashSet<string> roles)