Logging API doc additions (#77127)

dotnet · Oct 18, 2022 · 0ba8b10 · 0ba8b10
1 parent 0796729
commit 0ba8b10
Show file tree

Hide file tree

Showing 12 changed files with 50 additions and 0 deletions.
diff --git a/src/libraries/Microsoft.Extensions.Logging.Abstractions/src/NullLogger.cs b/src/libraries/Microsoft.Extensions.Logging.Abstractions/src/NullLogger.cs
@@ -15,6 +15,9 @@ public class NullLogger : ILogger
         /// </summary>
         public static NullLogger Instance { get; } = new NullLogger();
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="NullLogger"/> class.
+        /// </summary>
         private NullLogger()
         {
         }

diff --git a/.../Microsoft.Extensions.Logging.Configuration/src/LoggerProviderOptionsChangeTokenSource.cs b/.../Microsoft.Extensions.Logging.Configuration/src/LoggerProviderOptionsChangeTokenSource.cs
@@ -8,6 +8,9 @@ namespace Microsoft.Extensions.Logging.Configuration
     /// <inheritdoc />
     public class LoggerProviderOptionsChangeTokenSource<TOptions, TProvider> : ConfigurationChangeTokenSource<TOptions>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="LoggerProviderOptionsChangeTokenSource{TOptions, TProvider}"/> class.
+        /// </summary>
         public LoggerProviderOptionsChangeTokenSource(ILoggerProviderConfiguration<TProvider> providerConfiguration) : base(providerConfiguration.Configuration)
         {
         }

diff --git a/src/libraries/Microsoft.Extensions.Logging.Console/src/ConsoleFormatterOptions.cs b/src/libraries/Microsoft.Extensions.Logging.Console/src/ConsoleFormatterOptions.cs
@@ -12,6 +12,9 @@ namespace Microsoft.Extensions.Logging.Console
     /// </summary>
     public class ConsoleFormatterOptions
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ConsoleFormatterOptions"/> class.
+        /// </summary>
         public ConsoleFormatterOptions() { }
 
         /// <summary>

diff --git a/src/libraries/Microsoft.Extensions.Logging.Console/src/ConsoleLogger.cs b/src/libraries/Microsoft.Extensions.Logging.Console/src/ConsoleLogger.cs
@@ -9,6 +9,9 @@
 
 namespace Microsoft.Extensions.Logging.Console
 {
+    /// <summary>
+    /// A logger that writes messages in the console.
+    /// </summary>
     [UnsupportedOSPlatform("browser")]
     internal sealed class ConsoleLogger : ILogger
     {
@@ -38,6 +41,7 @@ internal ConsoleLogger(
         [ThreadStatic]
         private static StringWriter? t_stringWriter;
 
+        /// <inheritdoc />
         public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
         {
             if (!IsEnabled(logLevel))
@@ -65,11 +69,13 @@ public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Except
             _queueProcessor.EnqueueMessage(new LogMessageEntry(computedAnsiString, logAsError: logLevel >= Options.LogToStandardErrorThreshold));
         }
 
+        /// <inheritdoc />
         public bool IsEnabled(LogLevel logLevel)
         {
             return logLevel != LogLevel.None;
         }
 
+        /// <inheritdoc />
         public IDisposable BeginScope<TState>(TState state) where TState : notnull => ScopeProvider?.Push(state) ?? NullScope.Instance;
     }
 }
diff --git a/src/libraries/Microsoft.Extensions.Logging.Console/src/JsonConsoleFormatterOptions.cs b/src/libraries/Microsoft.Extensions.Logging.Console/src/JsonConsoleFormatterOptions.cs
@@ -10,6 +10,9 @@ namespace Microsoft.Extensions.Logging.Console
     /// </summary>
     public class JsonConsoleFormatterOptions : ConsoleFormatterOptions
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="JsonConsoleFormatterOptions"/> class.
+        /// </summary>
         public JsonConsoleFormatterOptions() { }
 
         /// <summary>

diff --git a/src/libraries/Microsoft.Extensions.Logging.Console/src/SimpleConsoleFormatterOptions.cs b/src/libraries/Microsoft.Extensions.Logging.Console/src/SimpleConsoleFormatterOptions.cs
@@ -8,6 +8,9 @@ namespace Microsoft.Extensions.Logging.Console
     /// </summary>
     public class SimpleConsoleFormatterOptions : ConsoleFormatterOptions
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SimpleConsoleFormatterOptions"/> class.
+        /// </summary>
         public SimpleConsoleFormatterOptions() { }
 
         /// <summary>

diff --git a/src/libraries/Microsoft.Extensions.Logging.Debug/src/DebugLoggerProvider.cs b/src/libraries/Microsoft.Extensions.Logging.Debug/src/DebugLoggerProvider.cs
@@ -15,6 +15,7 @@ public ILogger CreateLogger(string name)
             return new DebugLogger(name);
         }
 
+        /// <inheritdoc />
         public void Dispose()
         {
         }

diff --git a/src/libraries/Microsoft.Extensions.Logging.EventLog/src/EventLogLogger.cs b/src/libraries/Microsoft.Extensions.Logging.EventLog/src/EventLogLogger.cs
@@ -48,6 +48,9 @@ public EventLogLogger(string name, EventLogSettings settings, IExternalScopeProv
             _intermediateMessageSegmentSize = EventLog.MaxMessageSize - 2 * ContinuationString.Length;
         }
 
+        /// <summary>
+        /// The event log.
+        /// </summary>
         public IEventLog EventLog { get; }
 
         /// <inheritdoc />

diff --git a/src/libraries/Microsoft.Extensions.Logging.EventLog/src/WindowsEventLog.cs b/src/libraries/Microsoft.Extensions.Logging.EventLog/src/WindowsEventLog.cs
@@ -8,20 +8,32 @@
 
 namespace Microsoft.Extensions.Logging.EventLog
 {
+    /// <summary>
+    /// The windows event log.
+    /// </summary>
     [SupportedOSPlatform("windows")]
     internal sealed class WindowsEventLog : IEventLog
     {
         // https://msdn.microsoft.com/EN-US/library/windows/desktop/aa363679.aspx
         private const int MaximumMessageSize = 31839;
         private bool _enabled = true;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="WindowsEventLog"/> class.
+        /// </summary>
         public WindowsEventLog(string logName, string machineName, string sourceName)
         {
             DiagnosticsEventLog = new System.Diagnostics.EventLog(logName, machineName, sourceName);
         }
 
+        /// <summary>
+        /// The diagnostics event log.
+        /// </summary>
         public System.Diagnostics.EventLog DiagnosticsEventLog { get; }
 
+        /// <summary>
+        /// The maximum message size.
+        /// </summary>
         public int MaxMessageSize => MaximumMessageSize;
 
         public int? DefaultEventId { get; set; }

diff --git a/src/libraries/Microsoft.Extensions.Logging.EventSource/src/EventSourceLogger.cs b/src/libraries/Microsoft.Extensions.Logging.EventSource/src/EventSourceLogger.cs
@@ -50,6 +50,7 @@ public bool IsEnabled(LogLevel logLevel)
             return logLevel != LogLevel.None && logLevel >= Level;
         }
 
+        /// <inheritdoc />
         public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
         {
             if (!IsEnabled(logLevel))

diff --git a/src/libraries/Microsoft.Extensions.Logging.EventSource/src/EventSourceLoggerProvider.cs b/src/libraries/Microsoft.Extensions.Logging.EventSource/src/EventSourceLoggerProvider.cs
@@ -20,6 +20,10 @@ public class EventSourceLoggerProvider : ILoggerProvider
         private EventSourceLogger? _loggers; // Linked list of loggers that I have created
         private readonly LoggingEventSource _eventSource;
 
+        /// <summary>
+        /// Creates an instance of <see cref="EventSourceLoggerProvider"/>.
+        /// </summary>
+        /// <param name="eventSource">The logging event source.</param>
         public EventSourceLoggerProvider(LoggingEventSource eventSource)
         {
             ThrowHelper.ThrowIfNull(eventSource);

diff --git a/src/libraries/Microsoft.Extensions.Logging.TraceSource/src/TraceSourceLogger.cs b/src/libraries/Microsoft.Extensions.Logging.TraceSource/src/TraceSourceLogger.cs
@@ -7,15 +7,23 @@
 
 namespace Microsoft.Extensions.Logging.TraceSource
 {
+    /// <summary>
+    /// A logger that writes a trace source log message.
+    /// </summary>
     internal sealed class TraceSourceLogger : ILogger
     {
         private readonly DiagnosticsTraceSource _traceSource;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TraceSourceLogger"/> class.
+        /// </summary>
+        /// <param name="traceSource">trace source</param>
         public TraceSourceLogger(DiagnosticsTraceSource traceSource)
         {
             _traceSource = traceSource;
         }
 
+        /// <inheritdoc />
         public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
         {
             if (!IsEnabled(logLevel))