Merge pull request #193 from cerebrate/master

More XML comments for public members

src/LibLog/LogProviders/LibLogException.cs.pp

@@ -3,12 +3,12 @@
 {
     using System;
 
-	/// <summary>
+    /// <summary>
     /// Exception thrown by LibLog.
     /// </summary>
     public class LibLogException : Exception
     {
-		/// <summary>
+        /// <summary>
         /// Initializes a new LibLogException with the specified message.
         /// </summary>
         /// <param name="message">The message</param>
@@ -17,7 +17,7 @@
         {
         }
 
-		/// <summary>
+        /// <summary>
         /// Initializes a new LibLogException with the specified message and inner exception.
         /// </summary>
         /// <param name="message">The message.</param>

src/LibLog/LogProviders/LogMessageFormatter.cs.pp

@@ -2,8 +2,8 @@
 namespace $rootnamespace$.Logging.LogProviders
 {
     using System;
-    using System.Collections.Generic;
     using System.Diagnostics.CodeAnalysis;
+    using System.Collections.Generic;
     using System.Globalization;
     using System.Linq;
     using System.Text.RegularExpressions;

src/LibLog/LogProviders/LogProviderBase.cs

@@ -3,6 +3,9 @@
     using System;
     using System.Diagnostics.CodeAnalysis;
 
+    /// <summary>
+    ///     Base class for specific log providers.
+    /// </summary>
 #if LIBLOG_EXCLUDE_CODE_COVERAGE
     [ExcludeFromCodeCoverage]
 #endif
@@ -15,10 +18,18 @@ abstract class LogProviderBase : ILogProvider
     {
         private static readonly IDisposable NoopDisposableInstance = new DisposableAction();
         private readonly Lazy<OpenMdc> _lazyOpenMdcMethod;
+
+        /// <summary>
+        ///     Error message should initializing the log provider fail.
+        /// </summary>
         protected const string ErrorInitializingProvider = "Unable to log due to problem initializing the log provider. See inner exception for details.";
 
         private readonly Lazy<OpenNdc> _lazyOpenNdcMethod;
 
+        /// <summary>
+        ///     Initialize an instance of the <see cref="LogProviderBase"/> class by initializing the references
+        ///     to the nested and mapped diagnostics context-obtaining functions.
+        /// </summary>
         protected LogProviderBase()
         {
             _lazyOpenNdcMethod
@@ -27,30 +38,67 @@ protected LogProviderBase()
                 = new Lazy<OpenMdc>(GetOpenMdcMethod);
         }
 
+        /// <summary>
+        /// Gets the specified named logger.
+        /// </summary>
+        /// <param name="name">Name of the logger.</param>
+        /// <returns>The logger reference.</returns>
         public abstract Logger GetLogger(string name);
 
+        /// <summary>
+        /// Opens a nested diagnostics context. Not supported in EntLib logging.
+        /// </summary>
+        /// <param name="message">The message to add to the diagnostics context.</param>
+        /// <returns>A disposable that when disposed removes the message from the context.</returns>
         public IDisposable OpenNestedContext(string message)
         {
             return _lazyOpenNdcMethod.Value(message);
         }
 
+        /// <summary>
+        /// Opens a mapped diagnostics context. Not supported in EntLib logging.
+        /// </summary>
+        /// <param name="key">A key.</param>
+        /// <param name="value">A value.</param>
+        /// <param name="destructure">Determines whether to call the destructor or not.</param>
+        /// <returns>A disposable that when disposed removes the map from the context.</returns>
         public IDisposable OpenMappedContext(string key, object value, bool destructure = false)
         {
             return _lazyOpenMdcMethod.Value(key, value, destructure);
         }
 
+        /// <summary>
+        ///     Returns the provider-specific method to open a nested diagnostics context.
+        /// </summary>
+        /// <returns>A provider-specific method to open a nested diagnostics context.</returns>
         protected virtual OpenNdc GetOpenNdcMethod()
         {
             return _ => NoopDisposableInstance;
         }
 
+        /// <summary>
+        ///     Returns the provider-specific method to open a mapped diagnostics context.
+        /// </summary>
+        /// <returns>A provider-specific method to open a mapped diagnostics context.</returns>
         protected virtual OpenMdc GetOpenMdcMethod()
         {
             return (_, __, ___) => NoopDisposableInstance;
         }
 
+        /// <summary>
+        ///     Delegate defining the signature of the method opening a nested diagnostics context.
+        /// </summary>
+        /// <param name="message">The message to add to the diagnostics context.</param>
+        /// <returns>A disposable that when disposed removes the message from the context.</returns>
         protected delegate IDisposable OpenNdc(string message);
 
+        /// <summary>
+        ///     Delegate defining the signature of the method opening a mapped diagnostics context.
+        /// </summary>
+        /// <param name="key">A key.</param>
+        /// <param name="value">A value.</param>
+        /// <param name="destructure">Determines whether to call the destructor or not.</param>
+        /// <returns>A disposable that when disposed removes the map from the context.</returns>
         protected delegate IDisposable OpenMdc(string key, object value, bool destructure);
     }
 }

src/LibLog/LogProviders/LogProviderBase.cs.pp

@@ -4,6 +4,9 @@
     using System;
     using System.Diagnostics.CodeAnalysis;
 
+    /// <summary>
+    ///     Base class for specific log providers.
+    /// </summary>
 #if LIBLOG_EXCLUDE_CODE_COVERAGE
     [ExcludeFromCodeCoverage]
 #endif
@@ -16,10 +19,18 @@
     {
         private static readonly IDisposable NoopDisposableInstance = new DisposableAction();
         private readonly Lazy<OpenMdc> _lazyOpenMdcMethod;
+
+        /// <summary>
+        ///     Error message should initializing the log provider fail.
+        /// </summary>
         protected const string ErrorInitializingProvider = "Unable to log due to problem initializing the log provider. See inner exception for details.";
 
         private readonly Lazy<OpenNdc> _lazyOpenNdcMethod;
 
+        /// <summary>
+        ///     Initialize an instance of the <see cref="LogProviderBase"/> class by initializing the references
+        ///     to the nested and mapped diagnostics context-obtaining functions.
+        /// </summary>
         protected LogProviderBase()
         {
             _lazyOpenNdcMethod
@@ -28,30 +39,67 @@
                 = new Lazy<OpenMdc>(GetOpenMdcMethod);
         }
 
+        /// <summary>
+        /// Gets the specified named logger.
+        /// </summary>
+        /// <param name="name">Name of the logger.</param>
+        /// <returns>The logger reference.</returns>
         public abstract Logger GetLogger(string name);
 
+        /// <summary>
+        /// Opens a nested diagnostics context. Not supported in EntLib logging.
+        /// </summary>
+        /// <param name="message">The message to add to the diagnostics context.</param>
+        /// <returns>A disposable that when disposed removes the message from the context.</returns>
         public IDisposable OpenNestedContext(string message)
         {
             return _lazyOpenNdcMethod.Value(message);
         }
 
+        /// <summary>
+        /// Opens a mapped diagnostics context. Not supported in EntLib logging.
+        /// </summary>
+        /// <param name="key">A key.</param>
+        /// <param name="value">A value.</param>
+        /// <param name="destructure">Determines whether to call the destructor or not.</param>
+        /// <returns>A disposable that when disposed removes the map from the context.</returns>
         public IDisposable OpenMappedContext(string key, object value, bool destructure = false)
         {
             return _lazyOpenMdcMethod.Value(key, value, destructure);
         }
 
+        /// <summary>
+        ///     Returns the provider-specific method to open a nested diagnostics context.
+        /// </summary>
+        /// <returns>A provider-specific method to open a nested diagnostics context.</returns>
         protected virtual OpenNdc GetOpenNdcMethod()
         {
             return _ => NoopDisposableInstance;
         }
 
+        /// <summary>
+        ///     Returns the provider-specific method to open a mapped diagnostics context.
+        /// </summary>
+        /// <returns>A provider-specific method to open a mapped diagnostics context.</returns>
         protected virtual OpenMdc GetOpenMdcMethod()
         {
             return (_, __, ___) => NoopDisposableInstance;
         }
 
+        /// <summary>
+        ///     Delegate defining the signature of the method opening a nested diagnostics context.
+        /// </summary>
+        /// <param name="message">The message to add to the diagnostics context.</param>
+        /// <returns>A disposable that when disposed removes the message from the context.</returns>
         protected delegate IDisposable OpenNdc(string message);
 
+        /// <summary>
+        ///     Delegate defining the signature of the method opening a mapped diagnostics context.
+        /// </summary>
+        /// <param name="key">A key.</param>
+        /// <param name="value">A value.</param>
+        /// <param name="destructure">Determines whether to call the destructor or not.</param>
+        /// <returns>A disposable that when disposed removes the map from the context.</returns>
         protected delegate IDisposable OpenMdc(string key, object value, bool destructure);
     }
 }

src/LibLog/LoggerDelegate.cs.pp

@@ -4,7 +4,7 @@
     using System;
 
 #if !LIBLOG_PROVIDERS_ONLY || LIBLOG_PUBLIC
-	/// <summary>
+    /// <summary>
     /// Logger delegate.
     /// </summary>
     /// <param name="logLevel">The log level</param>