Docs for DefaultJsonSerializer/(i)ValueSerializer

src/NLog/IValueSerializer.cs

@@ -37,35 +37,43 @@
 namespace NLog
 {
     /// <summary>
-    /// Interface for serialization of object values into string format
+    /// Render a message template property to a string
+    /// 
+    /// If stringify is set, <see cref="StringifyObject"/> will be used
+    /// If serialize is set, <see cref="SerializeObject"/> will be used
+    /// Otherwise <see cref="FormatObject"/> will be used
     /// </summary>
     public interface IValueSerializer
     {
         /// <summary>
-        /// Serialization of an object into JSON format (or other destructure format)
+        /// Serialization of an object, e.g. JSON and append to <paramref name="builder"/>. Used if Serialize is set.
         /// </summary>
         /// <param name="value">The object to serialize to string.</param>
-        /// <param name="format">The format string for the object</param>
+        /// <param name="format">The format string for the value</param>
         /// <param name="formatProvider">An object that supplies culture-specific formatting information.</param>
         /// <param name="builder">Output destination.</param>
         /// <returns>Serialize succeeded (true/false)</returns>
         bool SerializeObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder);
 
         /// <summary>
-        /// Convert object into into quoted string value
+        /// Convert object into into string value and append to <paramref name="builder"/>. Used if Stringify is set.
         /// </summary>
-        /// <param name="value">The object to serialize to string.</param>
-        /// <param name="format">The format string for the object</param>
+        /// <param name="value">The object to convert to string.</param>
+        /// <param name="format">The format string for the value</param>
         /// <param name="formatProvider">An object that supplies culture-specific formatting information.</param>
         /// <param name="builder">Output destination.</param>
         /// <returns>Stringify succeeded (true/false)</returns>
         bool StringifyObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder);
 
         /// <summary>
-        /// Format object into into string value
+        /// Format object into into string value and append to <paramref name="builder"/>. Used for rendering the template properties.
         /// </summary>
-        /// <param name="value">The object to serialize to string.</param>
-        /// <param name="format">The format string for the object</param>
+        /// <remarks>
+        /// Stringify and Serialize isn't set
+        /// </remarks>
+        /// <remarks>This one is called if Stringify and Serialize isn't set for this property.</remarks>
+        /// <param name="value">The object to convert to string.</param>
+        /// <param name="format">The format string for the value</param>
         /// <param name="formatProvider">An object that supplies culture-specific formatting information.</param>
         /// <param name="builder">Output destination.</param>
         /// <returns>Formating succeeded (true/false)</returns>

src/NLog/MessageTemplates/ValueSerializer.cs

@@ -34,6 +34,7 @@
 using System;
 using System.Collections;
 using System.Text;
+using NLog.Config;
 using NLog.Internal;
 
 namespace NLog.MessageTemplates
@@ -61,7 +62,14 @@ private ValueSerializer()
 
         private readonly MruCache<Enum, string> _enumCache = new MruCache<Enum, string>(1500);
 
-        /// <inheritDoc/>
+        /// <summary>
+        /// Convert a object to a string without format and double quotes and append to <paramref name="builder"/>.
+        /// </summary>
+        /// <param name="value">The value to convert.</param>
+        /// <param name="format">Format, not used</param>
+        /// <param name="formatProvider">Format provider for the value.</param>
+        /// <param name="builder">Append to this</param>
+        /// <returns></returns>
         public bool StringifyObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder)
         {
             builder.Append('"');
@@ -70,7 +78,14 @@ public bool StringifyObject(object value, string format, IFormatProvider formatP
             return true;
         }
 
-        /// <inheritDoc/>
+        /// <summary>
+        /// Format an object to a readable string, or if it's an object, serialize
+        /// </summary>
+        /// <param name="value">The value to convert</param>
+        /// <param name="format"></param>
+        /// <param name="formatProvider"></param>
+        /// <param name="builder"></param>
+        /// <returns></returns>
         public bool FormatObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder)
         {
             if (SerializeSimpleObject(value, format, formatProvider, builder))
@@ -88,12 +103,27 @@ public bool FormatObject(object value, string format, IFormatProvider formatProv
             return true;
         }
 
-        /// <inheritDoc/>
+        /// <summary>
+        /// Serialize an object to JSON with the help of <see cref="ConfigurationItemFactory.JsonConverter"/>
+        /// </summary>
+        /// <param name="value"></param>
+        /// <param name="format"></param>
+        /// <param name="formatProvider"></param>
+        /// <param name="builder"></param>
+        /// <returns></returns>
         public bool SerializeObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder)
         {
             return Config.ConfigurationItemFactory.Default.JsonConverter.SerializeObject(value, builder);
         }
 
+        /// <summary>
+        /// Try serialising a scalar (string, int, NULL) or simple type (IFormattable)
+        /// </summary>
+        /// <param name="value"></param>
+        /// <param name="format"></param>
+        /// <param name="formatProvider"></param>
+        /// <param name="builder"></param>
+        /// <returns></returns>
         private bool SerializeSimpleObject(object value, string format, IFormatProvider formatProvider, StringBuilder builder)
         {
             // todo support all scalar types: 
@@ -173,6 +203,12 @@ private bool SerializeSimpleObject(object value, string format, IFormatProvider
             return false;
         }
 
+        /// <summary>
+        /// Apend a int type (byte, int) as string
+        /// </summary>
+        /// <param name="sb"></param>
+        /// <param name="value"></param>
+        /// <param name="objTypeCode"></param>
         private static void AppendIntegerAsString(StringBuilder sb, object value, TypeCode objTypeCode)
         {
             switch (objTypeCode)
@@ -245,6 +281,19 @@ private bool SerializeWithoutCyclicLoop(IEnumerable collection, string format, I
             }
         }
 
+        /// <summary>
+        /// Serialize Dictionary as JSON like structure, without { and }
+        /// </summary>
+        /// <example>
+        /// "FirstOrder"=true, "Previous login"=20-12-2017 14:55:32, "number of tries"=1
+        /// </example>
+        /// <param name="dictionary"></param>
+        /// <param name="format">formatstring of an item</param>
+        /// <param name="formatProvider"></param>
+        /// <param name="builder"></param>
+        /// <param name="objectsInPath"></param>
+        /// <param name="depth"></param>
+        /// <returns></returns>
         private bool SerializeDictionaryObject(IDictionary dictionary, string format, IFormatProvider formatProvider, StringBuilder builder, SingleItemOptimizedHashSet<object> objectsInPath, int depth)
         {
             bool separator = false;
@@ -289,6 +338,13 @@ private bool SerializeCollectionObject(IEnumerable collection, string format, IF
             return true;
         }
 
+        /// <summary>
+        /// Convert a value to a string with format and append to <paramref name="builder"/>.
+        /// </summary>
+        /// <param name="value">The value to convert.</param>
+        /// <param name="format">Format sting for the value.</param>
+        /// <param name="formatProvider">Format provider for the value.</param>
+        /// <param name="builder">Append to this</param>
         public static void FormatToString(object value, string format, IFormatProvider formatProvider, StringBuilder builder)
         {
             var stringValue = value as string;

src/NLog/Targets/DefaultJsonSerializer.cs

@@ -69,6 +69,9 @@ static DefaultJsonSerializer()
             instance = new DefaultJsonSerializer();
         }
 
+        /// <summary>
+        /// Private. Use <see cref="Instance"/>
+        /// </summary>
         private DefaultJsonSerializer()
         { }