Improve XML docs for obsoleted members with links to alternatives (#5498

)

src/NLog/Abstractions/ILoggerBase.cs

@@ -38,13 +38,16 @@ namespace NLog
     using JetBrains.Annotations;
 
     /// <summary>
+    /// Obsolete and replaced by <see cref="ILogger"/> with NLog v5.3.
+    /// 
     /// Logger with only generic methods (passing 'LogLevel' to methods) and core properties.
     /// </summary>
     [Obsolete("ILoggerBase should be replaced with ILogger. Marked obsolete with NLog v5.3")]
     [EditorBrowsable(EditorBrowsableState.Never)]
     public partial interface ILoggerBase
     {
         /// <summary>
+        /// Obsolete on the ILogger-interface, instead use <see cref="Logger.LoggerReconfigured"/> with NLog v5.3.
         /// Occurs when logger configuration changes.
         /// </summary>
         [Obsolete("LoggerReconfigured-EventHandler is very exotic for ILogger-interface. Instead use Logger.LoggerReconfigured. Marked obsolete with NLog v5.3")]
@@ -60,6 +63,7 @@ string Name
         }
 
         /// <summary>
+        /// Obsolete on the ILogger-interface, instead use <see cref="Logger.Factory"/> with NLog v5.3.
         /// Gets the factory that created this logger.
         /// </summary>
         [Obsolete("Factory-property is hard to mock for ILogger-interface. Instead use Logger.Factory. Marked obsolete with NLog v5.3")]

src/NLog/Abstractions/ISuppress.cs

@@ -40,6 +40,8 @@ namespace NLog
 #endif
 
     /// <summary>
+    /// Obsolete and replaced by <see cref="ILogger"/> with NLog v5.3.
+    /// 
     /// Provides an interface to execute System.Actions without surfacing any exceptions raised for that action.
     /// </summary>
     [Obsolete("ISuppress should be replaced with ILogger. Marked obsolete with NLog v5.3")]

src/NLog/Common/InternalLogger.cs

@@ -123,6 +123,7 @@ public static bool LogToConsoleError
         private static bool _logToConsoleError;
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="InternalLogger.LogWriter"/> with NLog v5.3.
         /// Gets or sets a value indicating whether internal messages should be written to the <see cref="System.Diagnostics"/>.Trace
         /// </summary>
         [Obsolete("Instead use InternalLogger.LogWriter. Marked obsolete with NLog v5.3")]
@@ -178,6 +179,7 @@ public static string LogFile
         public static TextWriter LogWriter { get; set; }
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="InternalEventOccurred"/> with NLog 5.3.
         /// Event written to the internal log.
         /// </summary>
         /// <remarks>

src/NLog/Config/LoggingRule.cs

@@ -121,6 +121,8 @@ public LoggingRule(string loggerNamePattern, Target target)
         public IList<Target> Targets => _targets;
 
         /// <summary>
+        /// Obsolete since too exotic feature with NLog v5.3.
+        /// 
         /// Gets a collection of child rules to be evaluated when this rule matches.
         /// </summary>
         [Obsolete("Very exotic feature without any unit-tests, not sure if it works. Marked obsolete with NLog v5.3")]

src/NLog/Config/MutableUnsafeAttribute.cs

@@ -37,6 +37,8 @@ namespace NLog.Config
     using System.ComponentModel;
 
     /// <summary>
+    /// Obsolete and replaced by <see cref="ThreadAgnosticImmutableAttribute"/> with NLog v5.3.
+    /// 
     /// Marks the layout or layout renderer depends on mutable objects from the LogEvent
     /// 
     /// This can be <see cref="LogEventInfo.Properties"/> or <see cref="LogEventInfo.Exception"/>

src/NLog/Config/XmlLoggingConfiguration.cs

@@ -281,6 +281,8 @@ public override LoggingConfiguration Reload()
         }
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> and <see cref="SetupBuilderExtensions.LoadConfigurationFromFile(ISetupBuilder, string, bool)"/> with NLog v5.2.
+        /// 
         /// Get file paths (including filename) for the possible NLog config files. 
         /// </summary>
         /// <returns>The file paths to the possible config file</returns>
@@ -292,6 +294,8 @@ public static IEnumerable<string> GetCandidateConfigFilePaths()
         }
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> and <see cref="SetupBuilderExtensions.LoadConfigurationFromFile(ISetupBuilder, string, bool)"/> with NLog v5.2.
+        /// 
         /// Overwrite the paths (including filename) for the possible NLog config files.
         /// </summary>
         /// <param name="filePaths">The file paths to the possible config file</param>
@@ -303,6 +307,8 @@ public static void SetCandidateConfigFilePaths(IEnumerable<string> filePaths)
         }
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> and <see cref="SetupBuilderExtensions.LoadConfigurationFromFile(ISetupBuilder, string, bool)"/> with NLog v5.2.
+        /// 
         /// Clear the candidate file paths and return to the defaults.
         /// </summary>
         [Obsolete("Replaced by chaining LogManager.Setup().LoadConfigurationFromFile(). Marked obsolete on NLog 5.2")]

src/NLog/Internal/CallSiteInformation.cs

@@ -137,6 +137,8 @@ public void SetCallerInfo(string callerClassName, string callerMethodName, strin
         }
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="LogEventInfo.CallerMemberName"/> or ${callsite} with NLog v5.3.
+        /// 
         /// Gets the stack frame of the method that did the logging.
         /// </summary>
         [Obsolete("Instead use ${callsite} or CallerMemberName. Marked obsolete on NLog 5.3")]

src/NLog/LayoutRenderers/LayoutRenderer.cs

@@ -251,7 +251,7 @@ protected CultureInfo GetCulture(LogEventInfo logEvent, CultureInfo layoutCultur
         }
 
         /// <summary>
-        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> with NLog v5.2
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> with NLog v5.2.
         /// 
         /// Register a custom layout renderer.
         /// </summary>
@@ -268,7 +268,7 @@ public static void Register(string name, [DynamicallyAccessedMembers(Dynamically
         }
 
         /// <summary>
-        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> with NLog v5.2
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> with NLog v5.2.
         /// 
         /// Register a custom layout renderer with a callback function <paramref name="func"/>. The callback receives the logEvent.
         /// </summary>
@@ -283,7 +283,7 @@ public static void Register(string name, Func<LogEventInfo, object> func)
         }
 
         /// <summary>
-        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> with NLog v5.2
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> with NLog v5.2.
         /// 
         /// Register a custom layout renderer with a callback function <paramref name="func"/>. The callback receives the logEvent and the current configuration.
         /// </summary>
@@ -299,7 +299,7 @@ public static void Register(string name, Func<LogEventInfo, LoggingConfiguration
         }
 
         /// <summary>
-        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> with NLog v5.2
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> with NLog v5.2.
         /// 
         /// Register a custom layout renderer with a callback function <paramref name="layoutRenderer"/>. The callback receives the logEvent and the current configuration.
         /// </summary>

src/NLog/LogEventInfo.cs

@@ -217,6 +217,8 @@ public int SequenceID
         public bool HasStackTrace => CallSiteInformation?.StackTrace != null;
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="LogEventInfo.CallerMemberName"/> or ${callsite} with NLog v5.3.
+        /// 
         /// Gets the stack frame of the method that did the logging.
         /// </summary>
         [Obsolete("Instead use ${callsite} or CallerMemberName. Marked obsolete on NLog 5.3")]

src/NLog/LogFactory.cs

@@ -132,6 +132,8 @@ public LogFactory()
         }
 
         /// <summary>
+        /// Obsolete instead use <see cref="LogFactory"/> default-constructor, and assign <see cref="Configuration"/> with NLog 5.0.
+        /// 
         /// Initializes a new instance of the <see cref="LogFactory" /> class.
         /// </summary>
         /// <param name="config">The config.</param>
@@ -769,6 +771,8 @@ protected virtual void OnConfigurationChanged(LoggingConfigurationChangedEventAr
 
 #if !NETSTANDARD1_3
         /// <summary>
+        /// Obsolete and replaced by <see cref="OnConfigurationReloaded"/> with NLog 5.2.
+        /// 
         /// Raises the event when the configuration is reloaded. 
         /// </summary>
         /// <param name="e">Event arguments</param>
@@ -906,6 +910,8 @@ public void Shutdown()
         }
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> and <see cref="SetupBuilderExtensions.LoadConfigurationFromFile(ISetupBuilder, string, bool)"/> with NLog v5.2.
+        /// 
         /// Get file paths (including filename) for the possible NLog config files. 
         /// </summary>
         /// <returns>The file paths to the possible config file</returns>
@@ -922,6 +928,8 @@ public IEnumerable<string> GetCandidateConfigFilePaths()
         }
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> and <see cref="SetupBuilderExtensions.LoadConfigurationFromFile(ISetupBuilder, string, bool)"/> with NLog v5.2.
+        /// 
         /// Get file paths (including filename) for the possible NLog config files. 
         /// </summary>
         /// <returns>The file paths to the possible config file</returns>
@@ -935,6 +943,8 @@ internal IEnumerable<string> GetCandidateConfigFilePaths(string filename)
         }
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> and <see cref="SetupBuilderExtensions.LoadConfigurationFromFile(ISetupBuilder, string, bool)"/> with NLog v5.2.
+        /// 
         /// Overwrite the candidates paths (including filename) for the possible NLog config files.
         /// </summary>
         /// <param name="filePaths">The file paths to the possible config file</param>
@@ -951,6 +961,8 @@ public void SetCandidateConfigFilePaths(IEnumerable<string> filePaths)
         }
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> and <see cref="SetupBuilderExtensions.LoadConfigurationFromFile(ISetupBuilder, string, bool)"/> with NLog v5.2.
+        /// 
         /// Clear the candidate file paths and return to the defaults.
         /// </summary>
         [Obsolete("Replaced by chaining LogFactory.Setup().LoadConfigurationFromFile(). Marked obsolete on NLog 5.2")]
@@ -1029,6 +1041,8 @@ internal Logger CreateNewLogger(Type loggerType, Func<Type, Logger> loggerCreato
         }
 
         /// <summary>
+        /// Obsolete and replaced by <see cref="LogManager.Setup()"/> and <see cref="SetupBuilderExtensions.LoadConfigurationFromFile(ISetupBuilder, string, bool)"/> with NLog v5.2.
+        /// 
         /// Loads logging configuration from file (Currently only XML configuration files supported)
         /// </summary>
         /// <param name="configFile">Configuration file to be read</param>