Revize d7aeccba

re #9570 Added code documentation to logger classes and properties

ld_client/LDClient/utils/loggers/ALogger.cs

@@ -2 +2 @@
 
 namespace LDClient.utils.loggers {
 
+    /// <summary>
+    /// This class implements all abstract functions of the logger.
+    /// It contains all functions (error, info, debug) that are present in any other standard logger.
+    /// Class is used as singleton design pattern
+    /// </summary>
     public abstract class ALogger : IDisposable {
 
+        /// <summary>
+        /// Logger verbosity type identifies how much information should be actually logged
+        /// </summary>
         private readonly LogVerbosity _verbosity;
+
+        /// <summary>
+        /// Current type of logger
+        /// </summary>
         private readonly LogFlow _logFlow;
 
+        /// <summary>
+        /// Queue of all not yet logged messages
+        /// </summary>
         private readonly Queue<Action> _queue = new();
+
+        /// <summary>
+        /// Synchronization prime used to identify if the is anything new in the queue 
+        /// </summary>
         private readonly ManualResetEvent _hasNewItems = new(false);
+        /// <summary>
+        /// Synchronization prime used to identify if the logger should be terminated
+        /// </summary>
         private readonly ManualResetEvent _terminate = new(false);
+        /// <summary>
+        /// Synchronization prime used to identify if the current thread is waiting
+        /// </summary>
         private readonly ManualResetEvent _waiting = new(false);
+
+        /// <summary>
+        /// Thread instance of logging thread
+        /// </summary>
         private readonly Thread _loggingThread;
 
+        /// <summary>
+        /// Instance of the default logger initialized with the lazy binding mechanism
+        /// </summary>
         private static readonly Lazy<ALogger> LazyLog = new(()
             => {
                 switch (Program.Config.LogFlowType) {
@@ -26 +58 @@
             }
         );
 
+        /// <summary>
+        /// Instance of the current logger type
+        /// </summary>
         public static ALogger Current => LazyLog.Value;
 
+        /// <summary>
+        /// Singleton constructor that initialized and starts the logger with arguments parsed by the config loader
+        /// </summary>
         protected ALogger() {
             _verbosity = Program.Config.LogVerbosityType;
             _logFlow = Program.Config.LogFlowType;
@@ -35 +73 @@
             _loggingThread.Start();
         }
 
+        /// <summary>
+        /// Creates new log with Info identifier
+        /// </summary>
+        /// <param name="message">Desired message to be logged</param>
         public void Info(string message) {
             Log(message, LogType.Info);
         }
 
+        /// <summary>
+        /// Creates new log with Debug identifier
+        /// </summary>
+        /// <param name="message">Desired message to be logged</param>
         public void Debug(string message) {
             Log(message, LogType.Debug);
         }
 
+        /// <summary>
+        /// Creates new log with Error identifier
+        /// </summary>
+        /// <param name="message">Desired message to be logged</param>
         public void Error(string message) {
             Log(message, LogType.Error);
         }
 
+        /// <summary>
+        /// Creates new log from the catched exception
+        /// </summary>
+        /// <param name="e">catched exception tha should be logged</param>
         public void Error(Exception e) {
             if (_verbosity != LogVerbosity.None) {
                 Log(UnwrapExceptionMessages(e), LogType.Error);
             }
         }
 
+        /// <summary>
+        /// Creates new string info about current logger configuration
+        /// </summary>
+        /// <returns></returns>
         public override string ToString() => $"Logger settings: [Type: {this.GetType().Name}, Verbosity: {_verbosity}, ";
-
+        
         protected abstract void CreateLog(string message);
 
+        /// <summary>
+        /// Waits for the logger to finish the logging
+        /// </summary>
         public void Flush() => _waiting.WaitOne();
 
+        /// <summary>
+        /// Function stops the logger thread
+        /// </summary>
         public void Dispose() {
             _terminate.Set();
             _loggingThread.Join();
         }
 
+        /// <summary>
+        /// Composes the log with actual timestamp, log type and its main message
+        /// </summary>
+        /// <param name="message">main message of the log</param>
+        /// <param name="logType">Type of the logged message</param>
+        /// <returns></returns>
         protected virtual string ComposeLogRow(string message, LogType logType) =>
             $"[{DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss,fff", CultureInfo.InvariantCulture)} - {logType}] - {message}";
 
+        /// <summary>
+        /// Function creates log from the catched exception
+        /// </summary>
+        /// <param name="ex">catched exception tha should be logged</param>
+        /// <returns></returns>
         protected virtual string UnwrapExceptionMessages(Exception? ex) =>
             ex == null ? string.Empty : $"{ex}, Inner exception: {UnwrapExceptionMessages(ex.InnerException)} ";
         
-
+        /// <summary>
+        /// Function that periodically processes message queue
+        /// </summary>
         private void ProcessQueue() {
             while (true) {
                 _waiting.Set();
+                //wait until there is new item in the queue or until termination invoked
                 var i = WaitHandle.WaitAny(new WaitHandle[] { _hasNewItems, _terminate });
+                //was the termination invoked?
                 if (i == 1) return;
                 _hasNewItems.Reset();
                 _waiting.Reset();
@@ -91 +170 @@
             }
         }
 
+        /// <summary>
+        /// Creates new log string from the current timestamp 
+        /// </summary>
+        /// <param name="message"></param>
+        /// <param name="logType"></param>
         private void Log(string message, LogType logType) {
             if (string.IsNullOrEmpty(message))
                 return;

ld_client/LDClient/utils/loggers/ConsoleLogger.cs

@@ -1 +1 @@
 namespace LDClient.utils.loggers {
     public class ConsoleLogger : ALogger {
+        /// <summary>
+        /// CreateLog function for the ConsoleLogger prints the desired message to the console
+        /// </summary>
+        /// <param name="message">Desired message to be printed</param>
         protected override void CreateLog(string message) {
             Console.WriteLine(message);
         }

ld_client/LDClient/utils/loggers/FileLogger.cs

@@ -4 +4 @@
 
 public class FileLogger : ALogger {
 
+    /// <summary>
+    /// Folder name for the created log files
+    /// </summary>
     private const string LogFolderName = "logs";
+    /// <summary>
+    /// Base name of the log file
+    /// </summary>
     private const string LogFileName = "app_info.log";
+    
     private readonly int _logChunkSize = Program.Config.LogChunkSize;
     private readonly int _logChunkMaxCount = Program.Config.LogChunkMaxCount;
     private readonly int _logArchiveMaxCount = Program.Config.LogArchiveMaxCount;
     private readonly int _logCleanupPeriod = Program.Config.LogCleanupPeriod;
 
+    /// <summary>
+    /// Destination folder used to store the created logs and zipped chunks
+    /// </summary>
     private const string LogFolderPath = $"ldClient\\{LogFolderName}";
 
+    /// <summary>
+    /// Flag that indicates that the log folder is already created
+    /// </summary>
     private bool _logDirExists;
 
+    /// <summary>
+    /// Creates one entry in the rotating file.
+    /// If the current log file is too big, it creates new log file.
+    /// If there is too many log files it archives them.
+    /// Deletes all archived files that are too old
+    /// </summary>
+    /// <param name="message">Desired message to be logged<</param>
     protected override void CreateLog(string message) {
 
         if (!_logDirExists) {
@@ -33 +53 @@
         sw.WriteLine(message);
     }
 
+    /// <summary>
+    /// Rotates last log file by creating new logging file in the process
+    /// </summary>
+    /// <param name="filePath">path to the last log file</param>
     private void Rotate(string filePath) {
         if (!File.Exists(filePath)) {
             return;
@@ -60 +84 @@
         DeleteOldArchives(logFolderContent);
     }
 
+    /// <summary>
+    /// Archives the all the last log files (chunks) 
+    /// </summary>
+    /// <param name="chunks">All log files that will be archived</param>
+    /// <param name="rotatedPath">path to the log files, which will be archived</param>
+    /// <param name="fileTime">current time stamp in string</param>
+    /// <param name="folderPath">path to to the exported archives</param>
     private void Archive(IEnumerable<FileSystemInfo> chunks, string rotatedPath, string fileTime, string? folderPath) {
 
         var archiveFolderInfo = Directory.CreateDirectory(Path.Combine(Path.GetDirectoryName(rotatedPath) ?? LogFolderPath, $"{LogFolderName}_{fileTime}"));
@@ -73 +104 @@
         Directory.Delete(archiveFolderInfo.FullName, true);
     }
 
+    /// <summary>
+    /// This function deletes all archives that are too old and exceeds the maximum zip files.
+    /// Cleanup period and zip max count can be specified in the configuration file.
+    /// </summary>
+    /// <param name="logFolderContent">filesystem info of the log folder</param>
     private void DeleteOldArchives(FileSystemInfo[] logFolderContent) {
 
         var archives = logFolderContent.Where(x => x.Extension.Equals(".zip", StringComparison.OrdinalIgnoreCase)).ToArray();
-
+        
         if (archives.Length <= _logArchiveMaxCount)
             return;
 
+        //find oldest archive in the folder
         var oldestArchive = archives.OrderBy(x => x.CreationTime).First();
         var cleanupDate = oldestArchive.CreationTime.AddDays(_logCleanupPeriod);
+        //is there any file older than specified cleanup cleanup period
         if (DateTime.Compare(cleanupDate, DateTime.Now) <= 0) {
             foreach (var file in logFolderContent) {
                 file.Delete();
@@ -90 +128 @@
             File.Delete(oldestArchive.FullName);
         }
     }
-
     public override string ToString() => $"{base.ToString()}, Chunk Size: {_logChunkSize}, Max chunk count: {_logChunkMaxCount}, Max log archive count: {_logArchiveMaxCount}, Cleanup period: {_logCleanupPeriod} days]";
 }

ld_client/LDClient/utils/loggers/LogFlow.cs

@@ -1 +1 @@
 namespace LDClient.utils.loggers {
+    /// <summary>
+    /// This enum specifies all possible types of loggers
+    /// </summary>
     public enum LogFlow {
+        /// <summary>
+        /// Console logger
+        /// </summary>
         Console = 0,
+        /// <summary>
+        /// Rotating file logger
+        /// </summary>
         File
     }
 }

ld_client/LDClient/utils/loggers/LogType.cs

@@ -1 +1 @@
 namespace LDClient.utils.loggers {
+    /// <summary>
+    /// Types of all possible logs
+    /// </summary>
     public enum LogType {
         Info = 0,
         Debug,

ld_client/LDClient/utils/loggers/LogVerbosity.cs

@@ -1 +1 @@
 namespace LDClient.utils.loggers {
+
+    /// <summary>
+    /// Enum specifies the verbosity of the log messages
+    /// </summary>
     public enum LogVerbosity {
         None = 0,
         Exceptions,