Merge pull request #117 from nblumhardt/v4-updates

Update to Serilog 4, tidy up

Author: nblumhardt

serilog-expressions.sln.DotSettings

@@ -1,4 +1,5 @@
 <wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=CI/@EntryIndexedValue">CI</s:String>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Acerola/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Comparand/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=delim/@EntryIndexedValue">True</s:Boolean>

src/Serilog.Expressions/Expressions/Ast/AccessorExpression.cs

@@ -14,6 +14,14 @@
 
 namespace Serilog.Expressions.Ast;
 
+/// <summary>
+/// An accessor retrieves a property from a (structured) object. For example, in the expression
+/// <code>Headers.ContentType</code> the <code>.</code> operator forms an accessor expression that
+/// retrieves the <code>ContentType</code> property from the <code>Headers</code> object.
+/// </summary>
+/// <remarks>Note that the AST type can represent accessors that cannot be validly written using
+/// <code>.</code> notation. In these cases, if the accessor is formatted back out as an expression,
+/// <see cref="IndexerExpression"/> notation will be used.</remarks>
 class AccessorExpression : Expression
 {
     public AccessorExpression(Expression receiver, string memberName)

src/Serilog.Expressions/Expressions/Ast/AmbientNameExpression.cs

@@ -14,6 +14,11 @@
 
 namespace Serilog.Expressions.Ast;
 
+/// <summary>
+/// An ambient name is generally a property name or built-in that appears standalone in an expression. For example,
+/// in <code>Headers.ContentType</code>, <code>Headers</code> is an ambient name that produces an
+/// <see cref="AmbientNameExpression"/>. Built-ins like <code>@Level</code> are also parsed as ambient names.
+/// </summary>
 class AmbientNameExpression : Expression
 {
     readonly bool _requiresEscape;

src/Serilog.Expressions/Expressions/Ast/ArrayExpression.cs

@@ -14,6 +14,13 @@
 
 namespace Serilog.Expressions.Ast;
 
+/// <summary>
+/// An array expression constructs an array from a list of elements. For example, <code>[1, 2, 3]</code> is an
+/// array expression. The items in an array expression can be literal values or expressions, like in the
+/// above example, or they can be spread expressions that describe zero or more elements to include in the
+/// list. Whether included via regular elements or spread expressions, undefined values are ignored and won't
+/// appear in the resulting array value.
+/// </summary>
 class ArrayExpression : Expression
 {
     public ArrayExpression(Element[] elements)

src/Serilog.Expressions/Expressions/Ast/CallExpression.cs

@@ -14,6 +14,10 @@
 
 namespace Serilog.Expressions.Ast;
 
+/// <summary>
+/// A <see cref="CallExpression"/> is a function call made up of the function name, parenthesised argument
+/// list, and optional postfix <code>ci</code> modifier. For example, <code>Substring(RequestPath, 0, 5)</code>.
+/// </summary>
 class CallExpression : Expression
 {
     public CallExpression(bool ignoreCase, string operatorName, params Expression[] operands)

src/Serilog.Expressions/Expressions/Ast/ConstantExpression.cs

@@ -17,6 +17,9 @@
 
 namespace Serilog.Expressions.Ast;
 
+/// <summary>
+/// A constant such as <code>'hello'</code>, <code>true</code>, <code>null</code>, or <code>123.45</code>.
+/// </summary>
 class ConstantExpression : Expression
 {
     public ConstantExpression(LogEventPropertyValue constant)
@@ -30,19 +33,14 @@ public override string ToString()
     {
         if (Constant is ScalarValue sv)
         {
-            switch (sv.Value)
+            return sv.Value switch
             {
-                case string s:
-                    return "'" + s.Replace("'", "''") + "'";
-                case true:
-                    return "true";
-                case false:
-                    return "false";
-                case IFormattable formattable:
-                    return formattable.ToString(null, CultureInfo.InvariantCulture);
-                default:
-                    return (sv.Value ?? "null").ToString() ?? "<ToString() returned null>";
-            }
+                string s => "'" + s.Replace("'", "''") + "'",
+                true => "true",
+                false => "false",
+                IFormattable formattable => formattable.ToString(null, CultureInfo.InvariantCulture),
+                _ => (sv.Value ?? "null").ToString() ?? "<ToString() returned null>"
+            };
         }
 
         return Constant.ToString();

src/Serilog.Expressions/Expressions/Ast/Element.cs

@@ -14,6 +14,7 @@
 
 namespace Serilog.Expressions.Ast;
 
-abstract class Element
-{
-}
+/// <summary>
+/// An element in an <see cref="ArrayExpression"/>.
+/// </summary>
+abstract class Element;

src/Serilog.Expressions/Expressions/Ast/Expression.cs

@@ -14,8 +14,15 @@
 
 namespace Serilog.Expressions.Ast;
 
+/// <summary>
+/// An AST node.
+/// </summary>
 abstract class Expression
 {
-    // Used only as an enabler for testing and debugging.
+    /// <summary>
+    /// The <see cref="ToString"/> representation of an <see cref="Expression"/> is <strong>not</strong>
+    /// guaranteed to be syntactically valid: this is provided for debugging purposes only.
+    /// </summary>
+    /// <returns>A textual representation of the expression.</returns>
     public abstract override string ToString();
 }

src/Serilog.Expressions/Expressions/Ast/IndexOfMatchExpression.cs

@@ -16,6 +16,10 @@
 
 namespace Serilog.Expressions.Ast;
 
+/// <summary>
+/// A non-syntax expression tree node used when compiling the <see cref="Operators.OpIndexOfMatch"/>,
+/// <see cref="Operators.OpIsMatch"/>, and SQL-style <code>like</code> expressions.
+/// </summary>
 class IndexOfMatchExpression : Expression
 {
     public Expression Corpus { get; }

src/Serilog.Expressions/Expressions/Ast/IndexerExpression.cs

@@ -14,6 +14,11 @@
 
 namespace Serilog.Expressions.Ast;
 
+/// <summary>
+/// An <see cref="IndexerExpression"/> retrieves a property from an object, by name, or an item from an array
+/// by zero-based numeric index. For example, <code>Headers['Content-Type']</code> and <code>Items[2]</code> are
+/// parsed as indexer expressions.
+/// </summary>
 class IndexerExpression : Expression
 {
     public Expression Receiver { get; }