Logging documentation.

docs/spec/logging.md

@@ -0,0 +1,54 @@
+# Perspex Logging
+
+Perspex uses [Serilog](https://github.com/serilog/serilog) for logging via
+the Perspex.Logging.Serilog assembly.
+
+The following method should be present in your App.xaml.cs file:
+
+```C#
+private void InitializeLogging()
+{
+#if DEBUG
+    SerilogLogger.Initialize(new LoggerConfiguration()
+        .MinimumLevel.Warning()
+        .WriteTo.Trace(outputTemplate: "{Area}: {Message}")
+        .CreateLogger());
+#endif
+}
+```
+
+By default, this logging setup will write log messages with a severity of
+`Warning` or higher to `System.Diagnostics.Trace`. See the [Serilog
+documentation](https://github.com/serilog/serilog/wiki/Configuration-Basics)
+for more information on the options here.
+
+## Areas
+
+Each Perspex log message has an "Area" that can be used to filter the log to
+include only the type of events that you are interested in. These are currently:
+
+- Property
+- Binding
+- Visual
+- Layout
+- Control
+
+To limit the log output to a specific area you can add a filter; for example
+to enable verbose logging but only about layout:
+
+```C#
+SerilogLogger.Initialize(new LoggerConfiguration()
+    .Filter.ByIncludingOnly(Matching.WithProperty("Area", LogArea.Layout))
+    .MinimumLevel.Verbose()
+    .WriteTo.Trace(outputTemplate: "{Area}: {Message}")
+    .CreateLogger());
+```
+
+## Removing Serilog
+
+If you don't want a dependency on Serilog in your application, simply remove
+the reference to Perspex.Logging.Serilog and the code that initializes it. If
+you do however still want some kinda of logging, there are two steps:
+
+- Implement `Perspex.Logging.ILogSink`
+- Assign your implementation to `Logger.Sink`

docs/spec/toc.yml

@@ -5,4 +5,6 @@
 - name: Defining Properties
   href: defining-properties.md
 - name: Working with Properties
-  href: working-with-properties.md
+  href: working-with-properties.md
+- name: Logging
+  href: logging.md

samples/BindingTest/App.xaml.cs

@@ -2,6 +2,7 @@
 using Perspex;
 using Perspex.Controls;
 using Perspex.Diagnostics;
+using Perspex.Logging;
 using Perspex.Logging.Serilog;
 using Perspex.Markup.Xaml;
 using Serilog;
@@ -41,7 +42,8 @@ namespace BindingTest
         {
 #if DEBUG
             SerilogLogger.Initialize(new LoggerConfiguration()
-                .MinimumLevel.Warning()
+                .Filter.ByIncludingOnly(Matching.WithProperty("Area", LogArea.Layout))
+                .MinimumLevel.Verbose()
                 .WriteTo.Trace(outputTemplate: "{Area}: {Message}")
                 .CreateLogger());
 #endif

src/Perspex.Base/Logging/ILogSink.cs

@@ -3,8 +3,19 @@
 
 namespace Perspex.Logging
 {
+    /// <summary>
+    /// Defines a sink for Perspex logging messages.
+    /// </summary>
     public interface ILogSink
     {
+        /// <summary>
+        /// Logs a new event.
+        /// </summary>
+        /// <param name="level">The log event level.</param>
+        /// <param name="area">The area that the event originates.</param>
+        /// <param name="source">The object from which the event originates.</param>
+        /// <param name="messageTemplate">The message template.</param>
+        /// <param name="propertyValues">The message property values.</param>
         void Log(
             LogEventLevel level,
             string area,

src/Perspex.Base/Logging/Logger.cs

@@ -1,15 +1,28 @@
 // Copyright (c) The Perspex Project. All rights reserved.
 // Licensed under the MIT license. See licence.md file in the project root for full license information.
 
-using System;
 using System.Runtime.CompilerServices;
 
 namespace Perspex.Logging
 {
+    /// <summary>
+    /// Logs perspex messages.
+    /// </summary>
     public static class Logger
     {
+        /// <summary>
+        /// Gets or sets the application-defined sink that recieves the messages.
+        /// </summary>
         public static ILogSink Sink { get; set; }
 
+        /// <summary>
+        /// Logs an event.
+        /// </summary>
+        /// <param name="level">The log event level.</param>
+        /// <param name="area">The area that the event originates.</param>
+        /// <param name="source">The object from which the event originates.</param>
+        /// <param name="messageTemplate">The message template.</param>
+        /// <param name="propertyValues">The message property values.</param>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static void Log(
             LogEventLevel level, 
@@ -21,6 +34,13 @@ namespace Perspex.Logging
             Sink?.Log(level, area, source, messageTemplate, propertyValues);
         }
 
+        /// <summary>
+        /// Logs an event with the <see cref="LogEventLevel.Verbose"/> level.
+        /// </summary>
+        /// <param name="area">The area that the event originates.</param>
+        /// <param name="source">The object from which the event originates.</param>
+        /// <param name="messageTemplate">The message template.</param>
+        /// <param name="propertyValues">The message property values.</param>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static void Verbose(
             string area,
@@ -31,6 +51,13 @@ namespace Perspex.Logging
             Log(LogEventLevel.Verbose, area, source, messageTemplate, propertyValues);
         }
 
+        /// <summary>
+        /// Logs an event with the <see cref="LogEventLevel.Debug"/> level.
+        /// </summary>
+        /// <param name="area">The area that the event originates.</param>
+        /// <param name="source">The object from which the event originates.</param>
+        /// <param name="messageTemplate">The message template.</param>
+        /// <param name="propertyValues">The message property values.</param>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static void Debug(
             string area,
@@ -41,6 +68,13 @@ namespace Perspex.Logging
             Log(LogEventLevel.Debug, area, source, messageTemplate, propertyValues);
         }
 
+        /// <summary>
+        /// Logs an event with the <see cref="LogEventLevel.Information"/> level.
+        /// </summary>
+        /// <param name="area">The area that the event originates.</param>
+        /// <param name="source">The object from which the event originates.</param>
+        /// <param name="messageTemplate">The message template.</param>
+        /// <param name="propertyValues">The message property values.</param>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static void Information(
             string area,
@@ -51,6 +85,13 @@ namespace Perspex.Logging
             Log(LogEventLevel.Information, area, source, messageTemplate, propertyValues);
         }
 
+        /// <summary>
+        /// Logs an event with the <see cref="LogEventLevel.Warning"/> level.
+        /// </summary>
+        /// <param name="area">The area that the event originates.</param>
+        /// <param name="source">The object from which the event originates.</param>
+        /// <param name="messageTemplate">The message template.</param>
+        /// <param name="propertyValues">The message property values.</param>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static void Warning(
             string area,
@@ -61,6 +102,13 @@ namespace Perspex.Logging
             Log(LogEventLevel.Warning, area, source, messageTemplate, propertyValues);
         }
 
+        /// <summary>
+        /// Logs an event with the <see cref="LogEventLevel.Error"/> level.
+        /// </summary>
+        /// <param name="area">The area that the event originates.</param>
+        /// <param name="source">The object from which the event originates.</param>
+        /// <param name="messageTemplate">The message template.</param>
+        /// <param name="propertyValues">The message property values.</param>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static void Error(
             string area,
@@ -71,6 +119,13 @@ namespace Perspex.Logging
             Log(LogEventLevel.Error, area, source, messageTemplate, propertyValues);
         }
 
+        /// <summary>
+        /// Logs an event with the <see cref="LogEventLevel.Fatal"/> level.
+        /// </summary>
+        /// <param name="area">The area that the event originates.</param>
+        /// <param name="source">The object from which the event originates.</param>
+        /// <param name="messageTemplate">The message template.</param>
+        /// <param name="propertyValues">The message property values.</param>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public static void Fatal(
             string area,