Improved documentation for SandCastle (#4926)

src/NLog/Config/AssemblyLoadingEventArgs.cs

@@ -41,10 +41,11 @@ namespace NLog.Config
     /// An assembly is trying to load. 
     /// </summary>
     public class AssemblyLoadingEventArgs : CancelEventArgs
-    {/// <summary>
-     /// New event args
-     /// </summary>
-     /// <param name="assembly"></param>
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AssemblyLoadingEventArgs" /> class.
+        /// </summary>
+        /// <param name="assembly">Assembly that have been loaded</param>
         public AssemblyLoadingEventArgs(Assembly assembly)
         {
             Assembly = assembly;

src/NLog/Config/NLogDependencyResolveException.cs

@@ -45,14 +45,18 @@ public sealed class NLogDependencyResolveException : Exception
         /// Typed we tried to resolve
         /// </summary>
         [NotNull] public Type ServiceType { get; }
-
-        /// <inheritdoc/>
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="NLogDependencyResolveException" /> class.
+        /// </summary>
         public NLogDependencyResolveException(string message, [NotNull] Type serviceType) : base(CreateFullMessage(serviceType, message))
         {
             ServiceType = serviceType ?? throw new ArgumentNullException(nameof(serviceType));
         }
 
-        /// <inheritdoc/>
+        /// <summary>
+        /// Initializes a new instance of the <see cref="NLogDependencyResolveException" /> class.
+        /// </summary>
         public NLogDependencyResolveException(string message, Exception innerException, [NotNull] Type serviceType) : base(CreateFullMessage(serviceType, message), innerException)
         {
             ServiceType = serviceType ?? throw new ArgumentNullException(nameof(serviceType));

src/NLog/Config/ServiceRepositoryUpdateEventArgs.cs

@@ -43,6 +43,7 @@ public class ServiceRepositoryUpdateEventArgs : EventArgs
         /// <summary>
         /// Initializes a new instance of the <see cref="ServiceRepositoryUpdateEventArgs" /> class.
         /// </summary>
+        /// <param name="serviceType">Type of service that have been registered</param>
         public ServiceRepositoryUpdateEventArgs(Type serviceType)
         {
             ServiceType = serviceType;

src/NLog/Contexts/ScopeContext.cs

@@ -38,13 +38,13 @@
 namespace NLog
 {
     /// <summary>
-    /// <see cref="ScopeContext"/> allows one to store state in the thread execution context. All LogEvents created
-    /// within a scope can include the scope state when wanted. The logical context scope supports both
-    /// scope-properties and scope-nested-state-stack (Similar to log4j2 ThreadContext)
+    /// <see cref="ScopeContext"/> stores state in the async thread execution context. All LogEvents created
+    /// within a scope can include the scope state in the target output. The logical context scope supports
+    /// both scope-properties and scope-nested-state-stack (Similar to log4j2 ThreadContext)
     /// </summary>
     /// <remarks>
     /// <see cref="MappedDiagnosticsLogicalContext"/> (MDLC), <see cref="MappedDiagnosticsContext"/> (MDC), <see cref="NestedDiagnosticsLogicalContext"/> (NDLC)
-    /// and <see cref="NestedDiagnosticsContext"/> (NDC) has been deprecated and replaced by <see cref="ScopeContext"/>.
+    /// and <see cref="NestedDiagnosticsContext"/> (NDC) have been deprecated and replaced by <see cref="ScopeContext"/>.
     /// 
     /// .NetCore (and .Net46) uses AsyncLocal for handling the thread execution context. Older .NetFramework uses System.Runtime.Remoting.CallContext
     /// </remarks>

src/NLog/Targets/AsyncTaskTarget.cs

@@ -49,6 +49,31 @@ namespace NLog.Targets
     /// <remarks>
     /// <a href="https://github.com/NLog/NLog/wiki/How-to-write-a-custom-async-target">See NLog Wiki</a>
     /// </remarks>
+    /// <example><code>
+    /// [Target("MyFirst")]
+    /// public sealed class MyFirstTarget : AsyncTaskTarget
+    /// {
+    ///    public MyFirstTarget()
+    ///    {
+    ///        this.Host = "localhost";
+    ///    }
+    ///     
+    ///    [RequiredParameter]
+    ///    public Layout Host { get; set; }
+    ///
+    ///    protected override Task WriteAsyncTask(LogEventInfo logEvent, CancellationToken token)
+    ///    {
+    ///        string logMessage = this.RenderLogEvent(this.Layout, logEvent);
+    ///        string hostName = this.RenderLogEvent(this.Host, logEvent);
+    ///        return SendTheMessageToRemoteHost(hostName, logMessage);
+    ///    }
+    ///
+    ///    private async Task SendTheMessageToRemoteHost(string hostName, string message)
+    ///    {
+    ///        // To be implemented
+    ///    }
+    /// }
+    /// </code></example>
     /// <seealso href="https://github.com/NLog/NLog/wiki/How-to-write-a-custom-async-target">Documentation on NLog Wiki</seealso>
     public abstract class AsyncTaskTarget : TargetWithContext
     {
@@ -186,7 +211,7 @@ protected override void InitializeTarget()
         }
 
         /// <summary>
-        /// Override this to create the actual logging task
+        /// Override this to provide async task for writing a single logevent.
         /// <example>
         /// Example of how to override this method, and call custom async method
         /// <code>
@@ -207,7 +232,7 @@ protected override void InitializeTarget()
         protected abstract Task WriteAsyncTask(LogEventInfo logEvent, CancellationToken cancellationToken);
 
         /// <summary>
-        /// Override this to create the actual logging task for handling batch of logevents
+        /// Override this to provide async task for writing a batch of logevents.
         /// </summary>
         /// <param name="logEvents">A batch of logevents.</param>
         /// <param name="cancellationToken">The cancellation token</param>

src/NLog/Targets/NLogViewerTarget.cs

@@ -149,11 +149,15 @@ public bool IncludeNdc
             set => Renderer.IncludeNdc = value;
         }
 
-        /// <inheritdoc/>
+        /// <summary>
+        /// Gets or sets the option to include all properties from the log events
+        /// </summary>
         /// <docgen category='Layout Options' order='10' />
         public bool IncludeEventProperties { get => Renderer.IncludeEventProperties; set => Renderer.IncludeEventProperties = value; }
 
-        /// <inheritdoc/>
+        /// <summary>
+        /// Gets or sets whether to include the contents of the <see cref="ScopeContext"/> properties-dictionary.
+        /// </summary>
         /// <docgen category='Layout Options' order='10' />
         public bool IncludeScopeProperties { get => Renderer.IncludeScopeProperties; set => Renderer.IncludeScopeProperties = value; }
 

src/NLog/Targets/TargetWithContext.cs

@@ -47,6 +47,31 @@ namespace NLog.Targets
     /// <remarks>
     /// <a href="https://github.com/NLog/NLog/wiki/How-to-write-a-custom-target-for-structured-logging">See NLog Wiki</a>
     /// </remarks>
+    /// <example><code>
+    /// [Target("MyFirst")]
+    /// public sealed class MyFirstTarget : TargetWithContext
+    /// {
+    ///    public MyFirstTarget()
+    ///    {
+    ///        this.Host = "localhost";
+    ///    }
+    ///     
+    ///    [RequiredParameter]
+    ///    public Layout Host { get; set; }
+    ///
+    ///    protected override void Write(LogEventInfo logEvent) 
+    ///    {
+    ///        string logMessage = this.RenderLogEvent(this.Layout, logEvent);
+    ///        string hostName = this.RenderLogEvent(this.Host, logEvent);
+    ///        return SendTheMessageToRemoteHost(hostName, logMessage);
+    ///    }
+    ///
+    ///    private void SendTheMessageToRemoteHost(string hostName, string message)
+    ///    {
+    ///        // To be implemented
+    ///    }
+    /// }
+    /// </code></example>
     /// <seealso href="https://github.com/NLog/NLog/wiki/How-to-write-a-custom-target-for-structured-logging">Documentation on NLog Wiki</seealso>
     public abstract class TargetWithContext : TargetWithLayout, IIncludeContext
     {
@@ -65,15 +90,21 @@ public sealed override Layout Layout
         }
         private TargetWithContextLayout _contextLayout;
 
-        /// <inheritdoc/>
+        /// <summary>
+        /// Gets or sets the option to include all properties from the log events
+        /// </summary>
         /// <docgen category='Layout Options' order='10' />
         public bool IncludeEventProperties { get => _contextLayout.IncludeEventProperties; set => _contextLayout.IncludeEventProperties = value; }
 
-        /// <inheritdoc/>
+        /// <summary>
+        /// Gets or sets whether to include the contents of the <see cref="ScopeContext"/> properties-dictionary.
+        /// </summary>
         /// <docgen category='Layout Options' order='10' />
         public bool IncludeScopeProperties { get => _contextLayout.IncludeScopeProperties; set => _contextLayout.IncludeScopeProperties = value; }
 
-        /// <inheritdoc/>
+        /// <summary>
+        /// Gets or sets whether to include the contents of the <see cref="ScopeContext"/> nested-state-stack.
+        /// </summary>
         /// <docgen category='Layout Options' order='10' />
         public bool IncludeScopeNested { get => _contextLayout.IncludeScopeNested; set => _contextLayout.IncludeScopeNested = value; }
 

src/NLog/Targets/Wrappers/LogEventDroppedEventArgs.cs

@@ -40,7 +40,10 @@ namespace NLog.Targets.Wrappers
     /// </summary>
     public class LogEventDroppedEventArgs : EventArgs
     {
-        /// <inheritdoc/>
+        /// <summary>
+        /// Initializes a new instance of the <see cref="LogEventDroppedEventArgs" /> class.
+        /// </summary>
+        /// <param name="logEventInfo">LogEvent that have been dropped</param>
         public LogEventDroppedEventArgs(LogEventInfo logEventInfo) => DroppedLogEventInfo = logEventInfo;
 
         /// <summary>

src/NLog/Targets/Wrappers/LogEventQueueGrowEventArgs.cs

@@ -44,7 +44,7 @@ namespace NLog.Targets.Wrappers
     public class LogEventQueueGrowEventArgs : EventArgs
     {
         /// <summary>
-        /// Contains <see cref="AsyncRequestQueue"/> items count and new queue size.
+        /// Initializes a new instance of the <see cref="LogEventQueueGrowEventArgs" /> class.
         /// </summary>
         /// <param name="newQueueSize">Required queue size</param>
         /// <param name="requestsCount">Current queue size</param>