Docs for others

dotnet/src/webdriver/Internal/Logging/ConsoleLogHandler.cs

@@ -1,8 +1,29 @@
+// <copyright file="ConsoleLogHandler.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
 using System;
 using System.Collections.Generic;
 
 namespace OpenQA.Selenium.Internal.Logging
 {
+    /// <summary>
+    /// Represents a log handler that writes log events to the console.
+    /// </summary>
     public class ConsoleLogHandler : ILogHandler
     {
         private static readonly Dictionary<LogEventLevel, string> _levelMap = new Dictionary<LogEventLevel, string>
@@ -14,11 +35,19 @@ public class ConsoleLogHandler : ILogHandler
             { LogEventLevel.Error, "ERR" }
         };
 
+        /// <summary>
+        /// Handles a log event by writing it to the console.
+        /// </summary>
+        /// <param name="logEvent">The log event to handle.</param>
         public void Handle(LogEvent logEvent)
         {
             Console.WriteLine($"{logEvent.Timestamp:HH:mm:ss.fff} {_levelMap[logEvent.Level]} {logEvent.IssuedBy.Name}: {logEvent.Message}");
         }
 
+        /// <summary>
+        /// Creates a new instance of the <see cref="ConsoleLogHandler"/> class.
+        /// </summary>
+        /// <returns>A new instance of the <see cref="ConsoleLogHandler"/> class.</returns>
         public ILogHandler Clone()
         {
             return this;

dotnet/src/webdriver/Internal/Logging/ILogContext.cs

@@ -1,23 +1,85 @@
+// <copyright file="ILogContext.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
 using System;
 
 namespace OpenQA.Selenium.Internal.Logging
 {
+    /// <summary>
+    /// Represents a logging context that provides methods for creating sub-contexts, retrieving loggers, emitting log messages, and configuring minimum log levels.
+    /// </summary>
     public interface ILogContext : IDisposable
     {
+        /// <summary>
+        /// Creates a new logging context.
+        /// </summary>
+        /// <returns>A new instance of <see cref="ILogContext"/>.</returns>
         ILogContext CreateContext();
 
+        /// <summary>
+        /// Creates a new logging context with the specified minimum log level.
+        /// </summary>
+        /// <param name="minimumLevel">The minimum log level for the new context.</param>
+        /// <returns>A new instance of <see cref="ILogContext"/> with the specified minimum log level.</returns>
         ILogContext CreateContext(LogEventLevel minimumLevel);
 
+        /// <summary>
+        /// Gets a logger for the specified type.
+        /// </summary>
+        /// <typeparam name="T">The type for which to retrieve the logger.</typeparam>
+        /// <returns>An instance of <see cref="ILogger"/> for the specified type.</returns>
         ILogger GetLogger<T>();
 
+        /// <summary>
+        /// Gets a logger for the specified type.
+        /// </summary>
+        /// <param name="type">The type for which to retrieve the logger.</param>
+        /// <returns>An instance of <see cref="ILogger"/> for the specified type.</returns>
         ILogger GetLogger(Type type);
 
+        /// <summary>
+        /// Emits a log message using the specified logger, log level, and message.
+        /// </summary>
+        /// <param name="logger">The logger to emit the log message.</param>
+        /// <param name="level">The log level of the message.</param>
+        /// <param name="message">The log message.</param>
         void EmitMessage(ILogger logger, LogEventLevel level, string message);
 
+        /// <summary>
+        /// Sets the minimum log level for the current context.
+        /// </summary>
+        /// <param name="level">The minimum log level.</param>
+        /// <returns>The current instance of <see cref="ILogContext"/> with the minimum log level set.</returns>
         ILogContext SetMinimumLevel(LogEventLevel level);
 
+        /// <summary>
+        /// Sets the minimum log level for the specified type in the current context.
+        /// </summary>
+        /// <param name="issuer">The type for which to set the minimum log level.</param>
+        /// <param name="level">The minimum log level.</param>
+        /// <returns>The current instance of <see cref="ILogContext"/> with the minimum log level set for the specified type.</returns>
         ILogContext SetMinimumLevel(Type issuer, LogEventLevel level);
 
+        /// <summary>
+        /// Adds a log handler to the current context.
+        /// </summary>
+        /// <param name="handler">The log handler to add.</param>
+        /// <returns>The current instance of <see cref="ILogContext"/> with the log handler added.</returns>
         ILogContext WithHandler(ILogHandler handler);
     }
 }

dotnet/src/webdriver/Internal/Logging/ILogHandler.cs

@@ -1,11 +1,38 @@
-using System;
+// <copyright file="ILogHandler.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
 
 namespace OpenQA.Selenium.Internal.Logging
 {
+    /// <summary>
+    /// Represents a log handler that handles log events.
+    /// </summary>
     public interface ILogHandler
     {
+        /// <summary>
+        /// Handles a log event.
+        /// </summary>
+        /// <param name="logEvent">The log event to handle.</param>
         void Handle(LogEvent logEvent);
 
+        /// <summary>
+        /// Creates a clone of the log handler.
+        /// </summary>
+        /// <returns>A clone of the log handler.</returns>
         ILogHandler Clone();
     }
 }

dotnet/src/webdriver/Internal/Logging/Log.cs

@@ -1,29 +1,77 @@
+// <copyright file="Log.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
 using System;
 
 namespace OpenQA.Selenium.Internal.Logging
 {
+    /// <summary>
+    /// Provides context aware logging functionality for the Selenium WebDriver.
+    /// </summary>
+    /// 
+    /// <remarks>
+    /// Use the following code to enable logging to console:
+    /// <code>
+    /// Log.SetMinimumLevel(LogEventLevel.Debug)).WithHandler(new ConsoleLogHandler());
+    /// </code>
+    ///
+    /// Or enable it per limited execution scope:
+    /// <code>
+    /// using (var ctx = Log.CreateContext(LogEventLevel.Trace))
+    /// {
+    ///   // do something
+    /// }
+    /// </code>
+    /// </remarks>
     public static class Log
     {
         private static readonly LogContextManager _logContextManager = new LogContextManager();
 
+        /// <summary>
+        /// Creates a new log context with the current context properties and the specified minimum log event level.
+        /// </summary>
+        /// <returns>The created log context.</returns>
         public static ILogContext CreateContext()
         {
-            var context = CurrentContext.CreateContext();
+            var context = _logContextManager.CurrentContext.CreateContext();
 
-            CurrentContext = context;
+            _logContextManager.CurrentContext = context;
 
             return context;
         }
 
+        /// <summary>
+        /// Creates a new log context with with the current context properties and the specified minimum log event level.
+        /// </summary>
+        /// <param name="minimumLevel">The minimum log event level.</param>
+        /// <returns>The created log context.</returns>
         public static ILogContext CreateContext(LogEventLevel minimumLevel)
         {
-            var context = CurrentContext.CreateContext(minimumLevel);
+            var context = _logContextManager.CurrentContext.CreateContext(minimumLevel);
 
-            CurrentContext = context;
+            _logContextManager.CurrentContext = context;
 
             return context;
         }
 
+        /// <summary>
+        /// Gets or sets the current log context.
+        /// </summary>
         internal static ILogContext CurrentContext
         {
             get
@@ -36,29 +84,55 @@ internal static ILogContext CurrentContext
             }
         }
 
+        /// <summary>
+        /// Gets a logger for the specified type.
+        /// </summary>
+        /// <typeparam name="T">The type to get the logger for.</typeparam>
+        /// <returns>The logger.</returns>
         internal static ILogger GetLogger<T>()
         {
-            return CurrentContext.GetLogger<T>();
+            return _logContextManager.CurrentContext.GetLogger<T>();
         }
 
+        /// <summary>
+        /// Gets a logger for the specified type.
+        /// </summary>
+        /// <param name="type">The type to get the logger for.</param>
+        /// <returns>The logger.</returns>
         internal static ILogger GetLogger(Type type)
         {
-            return CurrentContext.GetLogger(type);
+            return _logContextManager.CurrentContext.GetLogger(type);
         }
 
+        /// <summary>
+        /// Sets the minimum log event level for the current log context.
+        /// </summary>
+        /// <param name="level">The minimum log event level.</param>
+        /// <returns>The current log context.</returns>
         public static ILogContext SetMinimumLevel(LogEventLevel level)
         {
-            return CurrentContext.SetMinimumLevel(level);
+            return _logContextManager.CurrentContext.SetMinimumLevel(level);
         }
 
+        /// <summary>
+        /// Sets the minimum log event level for the specified issuer in the current log context.
+        /// </summary>
+        /// <param name="issuer">The issuer type.</param>
+        /// <param name="level">The minimum log event level.</param>
+        /// <returns>The current log context.</returns>
         public static ILogContext SetMinimumLevel(Type issuer, LogEventLevel level)
         {
-            return CurrentContext.SetMinimumLevel(issuer, level);
+            return _logContextManager.CurrentContext.SetMinimumLevel(issuer, level);
         }
 
+        /// <summary>
+        /// Adds a log handler to the current log context.
+        /// </summary>
+        /// <param name="handler">The log handler to add.</param>
+        /// <returns>The current log context.</returns>
         public static ILogContext WithHandler(ILogHandler handler)
         {
-            return CurrentContext.WithHandler(handler);
+            return _logContextManager.CurrentContext.WithHandler(handler);
         }
     }
 }

dotnet/src/webdriver/Internal/Logging/LogContext.cs

@@ -1,15 +1,37 @@
+// <copyright file="LogContext.cs" company="WebDriver Committers">
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
 using System.Linq;
 
 namespace OpenQA.Selenium.Internal.Logging
 {
+    /// <summary>
+    /// Represents a logging context that provides methods for creating sub-contexts, retrieving loggers, emitting log messages, and configuring minimum log levels.
+    /// </summary>
+    /// <inheritdoc cref="ILogContext"/>
     internal class LogContext : ILogContext
     {
         private ConcurrentDictionary<Type, ILogger> _loggers;
 
-        private IList<ILogHandler> _handlers;
+        private readonly IList<ILogHandler> _handlers;
 
         private LogEventLevel _level;