Documentation changes (#83)

src/Destructurama.Attributed/Attributed/AttributedDestructuringPolicy.cs

@@ -51,7 +51,7 @@ private CacheEntry CreateCacheEntry(Type type)
         var ti = type.GetTypeInfo();
         var classDestructurer = ti.GetCustomAttribute<ITypeDestructuringAttribute>();
         if (classDestructurer != null)
-            return new((o, f) => classDestructurer.CreateLogEventPropertyValue(o, f));
+            return new(classDestructurer.CreateLogEventPropertyValue);
 
         var properties = type.GetPropertiesRecursive().ToList();
         if (!_options.IgnoreNullProperties

src/Destructurama.Attributed/Attributed/AttributedDestructuringPolicyOptions.cs

@@ -1,3 +1,5 @@
+using Serilog.Events;
+
 namespace Destructurama.Attributed;
 
 /// <summary>
@@ -6,9 +8,9 @@ namespace Destructurama.Attributed;
 public class AttributedDestructuringPolicyOptions
 {
     /// <summary>
-    /// By setting IgnoreNullProperties to true no need to set [NotLoggedIfNull] for every logged property.
-    /// Custom types implementing IEnumerable, will be destructed as StructureValue and affected by IgnoreNullProperties 
-    /// only in case at least one property (or the type itself) has Destructurama attribute applied.
+    /// By setting this property to <see langword="true"/> no need to set <see cref="NotLoggedIfNullAttribute"/>
+    /// for every logged property. Custom types implementing IEnumerable, will be destructed as <see cref="StructureValue"/>
+    /// and affected by this property only in case at least one property (or the type itself) has Destructurama attribute applied.
     /// </summary>
     public bool IgnoreNullProperties { get; set; }
 }

src/Destructurama.Attributed/Attributed/IPropertyDestructuringAttribute.cs

@@ -19,15 +19,15 @@
 namespace Destructurama.Attributed;
 
 /// <summary>
-/// Base interfaces for all <see cref="Attribute"/>s that override how a property is destructured.
+/// Base interface for all Destructurama attributes that override how a property is destructured.
 /// </summary>
 public interface IPropertyDestructuringAttribute
 {
     /// <summary>
     /// Attempt to create a replacement <see cref="LogEventProperty"/> for a property.
     /// </summary>
     /// <param name="name">The current property name.</param>
-    /// <param name="value">The current property value</param>
+    /// <param name="value">The current property value.</param>
     /// <param name="propertyValueFactory">The current <see cref="ILogEventPropertyValueFactory"/>.</param>
     /// <param name="property">The <see cref="LogEventProperty"/> to use as a replacement.</param>
     /// <returns><code>true</code>If a replacement <see cref="LogEventProperty"/> has been derived.</returns>

src/Destructurama.Attributed/Attributed/IPropertyOptionalIgnoreAttribute.cs

@@ -1,11 +1,11 @@
 // Copyright 2020 Destructurama Contributors, Serilog Contributors
-// 
+//
 // Licensed 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.
@@ -15,16 +15,16 @@
 namespace Destructurama.Attributed;
 
 /// <summary>
-/// Base interfaces for all <see cref="Attribute"/>s that determine should a property be ignored.
+/// Base interface for all Destructurama attributes that determine should a property be ignored.
 /// </summary>
 public interface IPropertyOptionalIgnoreAttribute
 {
     /// <summary>
     /// Determine should a property be ignored
     /// </summary>
-    /// <param name="name">The current property name</param>
-    /// <param name="value">The current property value</param>
-    /// <param name="type">The current property type</param>
+    /// <param name="name">The current property name.</param>
+    /// <param name="value">The current property value.</param>
+    /// <param name="type">The current property type.</param>
     /// <returns></returns>
     bool ShouldPropertyBeIgnored(string name, object? value, Type type);
 }

src/Destructurama.Attributed/Attributed/ITypeDestructuringAttribute.cs

@@ -18,7 +18,7 @@
 namespace Destructurama.Attributed;
 
 /// <summary>
-/// Base interfaces for all <see cref="Attribute"/>s that override how a property type type is destructured.
+/// Base interface for all Destructurama attributes that override how a property type is destructured.
 /// </summary>
 public interface ITypeDestructuringAttribute
 {

src/Destructurama.Attributed/Attributed/LogAsScalarAttribute.cs

@@ -29,9 +29,11 @@ public class LogAsScalarAttribute : Attribute, ITypeDestructuringAttribute, IPro
     /// <summary>
     /// Construct a <see cref="LogAsScalarAttribute"/>.
     /// </summary>
-    /// <param name="isMutable">Whether the scalar value should be converted into a string before
-    /// being passed down the (asynchronous) logging pipeline. For mutable types, specify
-    /// <code>true</code>, otherwise leave as false.</param>
+    /// <param name="isMutable">
+    /// Whether the scalar value should be converted into a string before
+    /// being passed down the (asynchronous) logging pipeline. For mutable
+    /// types, specify <code>true</code>, otherwise leave as false.
+    /// </param>
     public LogAsScalarAttribute(bool isMutable = false)
     {
         _isMutable = isMutable;

src/Destructurama.Attributed/Attributed/LogMaskedAttribute.cs

@@ -29,14 +29,17 @@ public class LogMaskedAttribute : Attribute, IPropertyDestructuringAttribute
     /// If set, the property value will be set to this text.
     /// </summary>
     public string Text { get; set; } = DEFAULT_MASK;
+
     /// <summary>
     /// Shows the first x characters in the property value.
     /// </summary>
     public int ShowFirst { get; set; }
+
     /// <summary>
     /// Shows the last x characters in the property value.
     /// </summary>
     public int ShowLast { get; set; }
+
     /// <summary>
     /// If set, it will swap out each character with the default value. Note that this
     /// property will be ignored if <see cref="Text"/> has been set to custom value.

src/Destructurama.Attributed/Attributed/LogReplacedAttribute.cs

@@ -20,7 +20,7 @@
 namespace Destructurama.Attributed;
 
 /// <summary>
-/// Apply to a property to use a replace the current value.
+/// Apply to a property to replace the current value.
 /// </summary>
 [AttributeUsage(AttributeTargets.Property)]
 public class LogReplacedAttribute : Attribute, IPropertyDestructuringAttribute
@@ -29,7 +29,7 @@ public class LogReplacedAttribute : Attribute, IPropertyDestructuringAttribute
     private readonly string _replacement;
 
     /// <summary>
-    /// The RegexOptions that will be applied. Defaults to <see cref="RegexOptions.None"/>
+    /// The options that will be applied. Defaults to <see cref="RegexOptions.None"/>
     /// </summary>
     public RegexOptions Options { get; set; }
 

src/Destructurama.Attributed/Attributed/NotLoggedIfNullAttribute.cs

@@ -1,11 +1,11 @@
 // Copyright 2020 Destructurama Contributors, Serilog Contributors
-// 
+//
 // Licensed 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.
@@ -15,7 +15,7 @@
 namespace Destructurama.Attributed;
 
 /// <summary>
-/// Specified that a property with null value should not be included when destructuring an object for logging.
+/// Specified that a property with <see langword="null"/> value should not be included when destructuring an object for logging.
 /// </summary>
 [AttributeUsage(AttributeTargets.Property)]
 public class NotLoggedIfNullAttribute : Attribute, IPropertyOptionalIgnoreAttribute

src/Destructurama.Attributed/LoggerConfigurationAttributedExtensions.cs

@@ -33,14 +33,14 @@ public static class LoggerConfigurationAppSettingsExtensions
     public static LoggerConfiguration UsingAttributes(this LoggerDestructuringConfiguration configuration) =>
         configuration.With<AttributedDestructuringPolicy>();
 
-
     /// <summary>
+    /// Adds a custom <see cref="IDestructuringPolicy"/> to enable manipulation of how objects
+    /// are logged to Serilog using attributes.
     /// </summary>
     /// <param name="configuration">The logger configuration to apply configuration to.</param>
-    /// <param name="configure">Configure Destructurama options</param>
+    /// <param name="configure">Delegate to configure Destructurama options.</param>
     /// <returns>An object allowing configuration to continue.</returns>
-    public static LoggerConfiguration UsingAttributes(this LoggerDestructuringConfiguration configuration,
-        Action<AttributedDestructuringPolicyOptions> configure)
+    public static LoggerConfiguration UsingAttributes(this LoggerDestructuringConfiguration configuration, Action<AttributedDestructuringPolicyOptions> configure)
     {
         var policy = new AttributedDestructuringPolicy(configure);
         return configuration.With(policy);