[api-docs] Added TBD placeholders for Akka.Persistence.Sql.Common.csp…

…roj (#2482)

This PR is part of an ongoing commit for #2407. It adds placeholders for
missing/incomplete xmldoc comments.

[12/23]

src/contrib/persistence/Akka.Persistence.Sql.Common/InternalExtensions.cs

@@ -9,8 +9,16 @@
 
 namespace Akka.Persistence.Sql.Common
 {
+    /// <summary>
+    /// TBD
+    /// </summary>
     internal static class InternalExtensions
     {
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="type">TBD</param>
+        /// <returns>TBD</returns>
         public static string QualifiedTypeName(this Type type)
         {
             return type.FullName + ", " + type.Assembly.GetName().Name;

src/contrib/persistence/Akka.Persistence.Sql.Common/Journal/BatchingSqlJournal.cs

@@ -59,6 +59,9 @@ public sealed class ReplayFilterSettings
         /// <summary>
         /// Creates a new instance of the <see cref="ReplayFilterSettings"/> from provided HOCON <paramref name="config"/>.
         /// </summary>
+        /// <param name="config">TBD</param>
+        /// <exception cref="ArgumentException">TBD</exception>
+        /// <exception cref="ArgumentNullException">TBD</exception>
         public ReplayFilterSettings(Config config)
         {
             if (config == null) throw new ArgumentNullException(nameof(config), "No HOCON config was provided for replay filter settings");
@@ -80,6 +83,13 @@ public ReplayFilterSettings(Config config)
             IsDebug = config.GetBoolean("debug", false);
         }
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="mode">TBD</param>
+        /// <param name="windowSize">TBD</param>
+        /// <param name="maxOldWriters">TBD</param>
+        /// <param name="isDebug">TBD</param>
         public ReplayFilterSettings(ReplayFilterMode mode, int windowSize, int maxOldWriters, bool isDebug)
         {
             Mode = mode;
@@ -116,6 +126,9 @@ public sealed class CircuitBreakerSettings
         /// <summary>
         /// Creates a new instance of the <see cref="CircuitBreakerSettings"/> from provided HOCON <paramref name="config"/>.
         /// </summary>
+        /// <param name="config">TBD</param>
+        /// <exception cref="ArgumentNullException">TBD</exception>
+        /// <returns>TBD</returns>
         public CircuitBreakerSettings(Config config)
         {
             if (config == null) throw new ArgumentNullException(nameof(config));
@@ -125,6 +138,12 @@ public CircuitBreakerSettings(Config config)
             ResetTimeout = config.GetTimeSpan("reset-timeout", TimeSpan.FromSeconds(60));
         }
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="maxFailures">TBD</param>
+        /// <param name="callTimeout">TBD</param>
+        /// <param name="resetTimeout">TBD</param>
         public CircuitBreakerSettings(int maxFailures, TimeSpan callTimeout, TimeSpan resetTimeout)
         {
             MaxFailures = maxFailures;
@@ -197,6 +216,14 @@ public abstract class BatchingSqlJournalSetup
         /// </summary>
         public QueryConfiguration NamingConventions { get; }
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="config">TBD</param>
+        /// <param name="namingConventions">TBD</param>
+        /// <exception cref="ArgumentException">TBD</exception>
+        /// <exception cref="ArgumentNullException">TBD</exception>
+        /// <returns>TBD</returns>
         protected BatchingSqlJournalSetup(Config config, QueryConfiguration namingConventions)
         {
             if (config == null) throw new ArgumentNullException(nameof(config), "Sql journal settings cannot be initialized, because required HOCON section couldn't been found");
@@ -237,6 +264,19 @@ protected BatchingSqlJournalSetup(Config config, QueryConfiguration namingConven
             NamingConventions = namingConventions;
         }
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="connectionString">TBD</param>
+        /// <param name="maxConcurrentOperations">TBD</param>
+        /// <param name="maxBatchSize">TBD</param>
+        /// <param name="maxBufferSize">TBD</param>
+        /// <param name="autoInitialize">TBD</param>
+        /// <param name="connectionTimeout">TBD</param>
+        /// <param name="isolationLevel">TBD</param>
+        /// <param name="circuitBreakerSettings">TBD</param>
+        /// <param name="replayFilterSettings">TBD</param>
+        /// <param name="namingConventions">TBD</param>
         protected BatchingSqlJournalSetup(string connectionString, int maxConcurrentOperations, int maxBatchSize, int maxBufferSize, bool autoInitialize, TimeSpan connectionTimeout, IsolationLevel isolationLevel, CircuitBreakerSettings circuitBreakerSettings, ReplayFilterSettings replayFilterSettings, QueryConfiguration namingConventions)
         {
             ConnectionString = connectionString;
@@ -445,6 +485,10 @@ public RequestChunk(int chunkId, IJournalRequest[] requests)
         private readonly CircuitBreaker _circuitBreaker;
         private int _remainingOperations;
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="setup">TBD</param>
         protected BatchingSqlJournal(BatchingSqlJournalSetup setup)
         {
             Setup = setup;
@@ -528,6 +572,9 @@ WHERE e.{conventions.OrderingColumnName} > @Ordering AND e.{conventions.TagsColu
                 )";
         }
 
+        /// <summary>
+        /// TBD
+        /// </summary>
         protected override void PreStart()
         {
             if (Setup.AutoInitialize)
@@ -548,7 +595,12 @@ protected override void PreStart()
 
             base.PreStart();
         }
-
+
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="message">TBD</param>
+        /// <returns>TBD</returns>
         protected sealed override bool Receive(object message)
         {
             if (message is WriteMessages) BatchRequest((IJournalRequest)message);
@@ -697,6 +749,7 @@ private void NotifyNewPersistenceIdAdded(string persistenceId)
         /// Tries to add incoming <paramref name="message"/> to <see cref="Buffer"/>.
         /// Also checks if any DB connection has been released and next batch can be processed.
         /// </summary>
+        /// <param name="message">TBD</param>
         protected void BatchRequest(IJournalRequest message)
         {
             if (Buffer.Count > Setup.MaxBufferSize)
@@ -712,6 +765,7 @@ protected void BatchRequest(IJournalRequest message)
         /// due to buffer overflow. Overflow is controlled by max buffer size and can be set using 
         /// <see cref="BatchingSqlJournalSetup.MaxBufferSize"/> setting.
         /// </summary>
+        /// <param name="request">TBD</param>
         protected virtual void OnBufferOverflow(IJournalMessage request)
         {
             Log.Warning("Batching journal buffer limit has been reached. Denying a request [{0}].", request);
@@ -1124,8 +1178,8 @@ protected virtual void WriteEvent(TCommand command, IPersistentRepresentation pe
         /// <summary>
         /// Returns a persitent representation of an event read from a current row in the database.
         /// </summary>
-        /// <param name="reader"></param>
-        /// <returns></returns>
+        /// <param name="reader">TBD</param>
+        /// <returns>TBD</returns>
         protected virtual IPersistentRepresentation ReadEvent(DbDataReader reader)
         {
             var persistenceId = reader.GetString(PersistenceIdIndex);
@@ -1145,6 +1199,8 @@ protected virtual IPersistentRepresentation ReadEvent(DbDataReader reader)
         /// <summary>
         /// Creates a new database connection from a given <paramref name="connectionString"/>.
         /// </summary>
+        /// <param name="connectionString">TBD</param>
+        /// <returns>TBD</returns>
         protected abstract TConnection CreateConnection(string connectionString);
 
         /// <summary>
@@ -1190,10 +1246,19 @@ private void CompleteBatch(BatchComplete msg)
         }
     }
 
+    /// <summary>
+    /// TBD
+    /// </summary>
     public class JournalBufferOverflowException : AkkaException
     {
+        /// <summary>
+        /// TBD
+        /// </summary>
         public static readonly JournalBufferOverflowException Instance = new JournalBufferOverflowException();
 
+        /// <summary>
+        /// TBD
+        /// </summary>
         public JournalBufferOverflowException() : base(
             "Batching journal buffer has been overflowed. This may happen as an effect of burst of persistent actors "
             + "requests incoming faster than the underlying database is able to fullfil them. You may modify "

src/contrib/persistence/Akka.Persistence.Sql.Common/Journal/ITimestampProvider.cs

@@ -17,6 +17,8 @@ public interface ITimestampProvider
         /// <summary>
         /// Generates timestamp for provided <see cref="IPersistentRepresentation"/> message.
         /// </summary>
+        /// <param name="message">TBD</param>
+        /// <returns>TBD</returns>
         long GenerateTimestamp(IPersistentRepresentation message);
     }
 
@@ -25,6 +27,11 @@ public interface ITimestampProvider
     /// </summary>
     public sealed class DefaultTimestampProvider : ITimestampProvider
     {
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="message">TBD</param>
+        /// <returns>TBD</returns>
         public long GenerateTimestamp(IPersistentRepresentation message) => DateTime.UtcNow.Ticks;
     }
 }

src/contrib/persistence/Akka.Persistence.Sql.Common/Journal/Messages.cs

@@ -1,5 +1,5 @@
 //-----------------------------------------------------------------------
-// <copyright file="JournalDbEngine.cs" company="Akka.NET Project">
+// <copyright file="Messages.cs" company="Akka.NET Project">
 //     Copyright (C) 2009-2016 Typesafe Inc. <http://www.typesafe.com>
 //     Copyright (C) 2013-2016 Akka.NET project <https://github.com/akkadotnet/akka.net>
 // </copyright>
@@ -17,13 +17,40 @@ namespace Akka.Persistence.Sql.Common.Journal
     /// </summary>
     public sealed class JournalEntry
     {
+        /// <summary>
+        /// TBD
+        /// </summary>
         public readonly string PersistenceId;
+        /// <summary>
+        /// TBD
+        /// </summary>
         public readonly long SequenceNr;
+        /// <summary>
+        /// TBD
+        /// </summary>
         public readonly bool IsDeleted;
+        /// <summary>
+        /// TBD
+        /// </summary>
         public readonly string Manifest;
+        /// <summary>
+        /// TBD
+        /// </summary>
         public readonly DateTime Timestamp;
+        /// <summary>
+        /// TBD
+        /// </summary>
         public readonly object Payload;
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="persistenceId">TBD</param>
+        /// <param name="sequenceNr">TBD</param>
+        /// <param name="isDeleted">TBD</param>
+        /// <param name="manifest">TBD</param>
+        /// <param name="timestamp">TBD</param>
+        /// <param name="payload">TBD</param>
         public JournalEntry(string persistenceId, long sequenceNr, bool isDeleted, string manifest, DateTime timestamp, object payload)
         {
             PersistenceId = persistenceId;
@@ -55,6 +82,12 @@ public struct EventId
         /// </summary>
         public readonly string PersistenceId;
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="id">TBD</param>
+        /// <param name="sequenceNr">TBD</param>
+        /// <param name="persistenceId">TBD</param>
         public EventId(long id, long sequenceNr, string persistenceId)
         {
             Id = id;
@@ -68,8 +101,15 @@ public EventId(long id, long sequenceNr, string persistenceId)
     /// </summary>
     public sealed class WriteJournalBatch
     {
+        /// <summary>
+        /// TBD
+        /// </summary>
         public readonly IDictionary<IPersistentRepresentation, IImmutableSet<string>> EntryTags;
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="entryTags">TBD</param>
         public WriteJournalBatch(IDictionary<IPersistentRepresentation, IImmutableSet<string>> entryTags)
         {
             EntryTags = entryTags;
@@ -81,8 +121,15 @@ public WriteJournalBatch(IDictionary<IPersistentRepresentation, IImmutableSet<st
     /// </summary>
     public sealed class AllPersistenceIds
     {
+        /// <summary>
+        /// TBD
+        /// </summary>
         public readonly ImmutableArray<string> Ids;
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <param name="ids">TBD</param>
         public AllPersistenceIds(ImmutableArray<string> ids)
         {
             Ids = ids;

src/contrib/persistence/Akka.Persistence.Sql.Common/Journal/MultiValueDictionaryExtensions.cs

@@ -1,9 +1,28 @@
-using System.Collections.Generic;
+//-----------------------------------------------------------------------
+// <copyright file="MultiValueDictionaryExtensions.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.Generic;
 
 namespace Akka.Persistence.Sql.Common.Journal
 {
+    /// <summary>
+    /// TBD
+    /// </summary>
     internal static class MultiValueDictionaryExtensions
     {
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <typeparam name="TKey">TBD</typeparam>
+        /// <typeparam name="TVal">TBD</typeparam>
+        /// <param name="dictionary">TBD</param>
+        /// <param name="key">TBD</param>
+        /// <param name="item">TBD</param>
+        /// <returns>TBD</returns>
         public static void AddItem<TKey, TVal>(this Dictionary<TKey, HashSet<TVal>> dictionary, TKey key, TVal item)
         {
             HashSet<TVal> bucket;
@@ -16,6 +35,15 @@ public static void AddItem<TKey, TVal>(this Dictionary<TKey, HashSet<TVal>> dict
             bucket.Add(item);
         }
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <typeparam name="TKey">TBD</typeparam>
+        /// <typeparam name="TVal">TBD</typeparam>
+        /// <param name="dictionary">TBD</param>
+        /// <param name="key">TBD</param>
+        /// <param name="item">TBD</param>
+        /// <returns>TBD</returns>
         public static void RemoveItem<TKey, TVal>(this Dictionary<TKey, HashSet<TVal>> dictionary, TKey key, TVal item)
         {
             HashSet<TVal> bucket;
@@ -28,6 +56,14 @@ public static void RemoveItem<TKey, TVal>(this Dictionary<TKey, HashSet<TVal>> d
             }
         }
 
+        /// <summary>
+        /// TBD
+        /// </summary>
+        /// <typeparam name="TKey">TBD</typeparam>
+        /// <typeparam name="TVal">TBD</typeparam>
+        /// <param name="dictionary">TBD</param>
+        /// <param name="item">TBD</param>
+        /// <returns>TBD</returns>
         public static void RemoveItem<TKey, TVal>(this Dictionary<TKey, HashSet<TVal>> dictionary, TVal item)
         {
             foreach (var entry in dictionary)