Add missing documentation for the formatting feature

Author: Kaliumhexacyanoferrat

Modules/Controllers/Extensions.cs

@@ -22,7 +22,8 @@ public static class Extensions
         /// <param name="builder">The layout the controller should be added to</param>
         /// <param name="path">The path that should be handled by the controller</param>
         /// <param name="injectors">Optionally the injectors to be used by this controller</param>
-        /// <param name="formats">Optionally the formats to be used by this controller</param>
+        /// <param name="serializers">Optionally the serializers to be used by this controller</param>
+        /// <param name="formatters">Optionally the formatters to be used by this controller</param>
         public static LayoutBuilder AddController<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] T>(this LayoutBuilder builder, string path, IBuilder<InjectionRegistry>? injectors = null, IBuilder<SerializationRegistry>? serializers = null, IBuilder<FormatterRegistry>? formatters = null) where T : new()
         {
             builder.Add(path, Controller.From<T>().Configured(injectors, serializers, formatters));
@@ -36,7 +37,8 @@ public static class Extensions
         /// <typeparam name="T">The type of the controller used to handle requests</typeparam>
         /// <param name="builder">The layout the controller should be added to</param>
         /// <param name="injectors">Optionally the injectors to be used by this controller</param>
-        /// <param name="formats">Optionally the formats to be used by this controller</param>
+        /// <param name="serializers">Optionally the serializers to be used by this controller</param>
+        /// <param name="formatters">Optionally the formatters to be used by this controller</param>
         public static LayoutBuilder IndexController<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] T>(this LayoutBuilder builder, IBuilder<InjectionRegistry>? injectors = null, IBuilder<SerializationRegistry>? serializers = null, IBuilder<FormatterRegistry>? formatters = null) where T : new()
         {
             builder.Add(Controller.From<T>().Configured(injectors, serializers, formatters));

Modules/Controllers/Provider/ControllerBuilder.cs

@@ -31,13 +31,13 @@ public ControllerBuilder<T> Serializers(IBuilder<SerializationRegistry> registry
             return this;
         }
 
-        public ControllerBuilder<T> Injectors(IBuilder<InjectionRegistry>? registry)
+        public ControllerBuilder<T> Injectors(IBuilder<InjectionRegistry> registry)
         {
             _Injection = registry;
             return this;
         }
 
-        public ControllerBuilder<T> Formatters(IBuilder<FormatterRegistry>? registry)
+        public ControllerBuilder<T> Formatters(IBuilder<FormatterRegistry> registry)
         {
             _Formatters = registry;
             return this;

Modules/Conversion/Extensions.cs

@@ -16,6 +16,7 @@ public static class Extensions
         /// </summary>
         /// <param name="value">The value to be converted</param>
         /// <param name="type">The target type to convert the value to</param>
+        /// <param name="formatters">The formatting to be used to actually perform the conversion</param>
         /// <returns>The converted value</returns>
         public static object? ConvertTo(this string? value, Type type, FormatterRegistry formatters)
         {

Modules/Conversion/Formatters/BoolFormatter.cs

@@ -10,11 +10,11 @@ public sealed class BoolFormatter : IFormatter
 
         public object? Read(string value, Type type)
         {
-            if (value == "1" || value == "on")
+            if (value == "1" || Compare(value, "on") || Compare(value, "true"))
             {
                 return true;
             }
-            else if (value == "0" || value == "off") 
+            else if (value == "0" || Compare(value, "off") || Compare(value, "false")) 
             {
                 return false; 
             }
@@ -24,6 +24,8 @@ public sealed class BoolFormatter : IFormatter
 
         public string? Write(object value, Type type) => ((bool)value) ? "1" : "0";
 
+        private static bool Compare(string value, string expected) => string.Equals(value, expected, StringComparison.InvariantCultureIgnoreCase);
+
     }
 
 }

Modules/Conversion/Formatters/FormatterBuilder.cs

@@ -11,6 +11,10 @@ public sealed class FormatterBuilder : IBuilder<FormatterRegistry>
 
         #region Functionality
 
+        /// <summary>
+        /// Adds the given formatter to the registry.
+        /// </summary>
+        /// <param name="formatter">The formatter to be added</param>
         public FormatterBuilder Add(IFormatter formatter)
         {
             _Registry.Add(formatter);
@@ -19,6 +23,10 @@ public FormatterBuilder Add(IFormatter formatter)
 
         public FormatterBuilder Add<T>() where T : IFormatter, new() => Add(new T());
 
+        /// <summary>
+        /// Builds the formatter registry based on the configuration.
+        /// </summary>
+        /// <returns>The newly created formatter registry</returns>
         public FormatterRegistry Build()
         {
             return new FormatterRegistry(_Registry);

Modules/Conversion/Formatters/IFormatter.cs

@@ -3,13 +3,41 @@
 namespace GenHTTP.Modules.Conversion.Formatters
 {
 
+    /// <summary>
+    /// Allows to add support for a specific type to be used as a parameter
+    /// of a web service or controller as well as in form encoded data.
+    /// </summary>
     public interface IFormatter
     {
 
+        /// <summary>
+        /// Checks, whether the formatter is capable of handling the given type.
+        /// </summary>
+        /// <param name="type">The type to be checked</param>
+        /// <returns>true, if the formatter can be used to read and write such types</returns>
         bool CanHandle(Type type);
 
+        /// <summary>
+        /// Converts the given string into the specified type.
+        /// </summary>
+        /// <param name="value">The value to be converted</param>
+        /// <param name="type">The type to convert the value to</param>
+        /// <returns>The value converted into the given type</returns>
+        /// <remarks>
+        /// Used by the framework to read parameters to be passed to controllers or the like.
+        /// </remarks>
         object? Read(string value, Type type);
 
+        /// <summary>
+        /// Converts the given object instance of the given type into a string representation.
+        /// </summary>
+        /// <param name="value">The value to be formatted</param>
+        /// <param name="type">The declared type of the value</param>
+        /// <returns>The string representation of the given value</returns>
+        /// <remarks>
+        /// Used by the framework to serialize a single value into the response's body 
+        /// or to generate form encoded data.
+        /// </remarks>
         string? Write(object value, Type type);
 
     }

Modules/Conversion/Formatting.cs

@@ -3,9 +3,18 @@
 namespace GenHTTP.Modules.Conversion
 {
 
+    /// <summary>
+    /// Entry point to customize the string representation generated for
+    /// various types that can be returned or read by services.
+    /// </summary>
     public static class Formatting
     {
 
+        /// <summary>
+        /// The default formatters to be used with support for enums, GUIDs,
+        /// primitive types and strings.
+        /// </summary>
+        /// <returns>The default formatters</returns>
         public static FormatterBuilder Default()
         {
             return new FormatterBuilder().Add<StringFormatter>()
@@ -16,6 +25,11 @@ public static FormatterBuilder Default()
                                          .Add<PrimitiveFormatter>();
         }
 
+        /// <summary>
+        /// Creates an empty formatter registry that can be extended
+        /// as needed.
+        /// </summary>
+        /// <returns>An empty formatter registry</returns>
         public static FormatterBuilder Empty() => new FormatterBuilder();
 
     }

Modules/Functional/Provider/InlineBuilder.cs

@@ -52,7 +52,11 @@ public InlineBuilder Injectors(IBuilder<InjectionRegistry> registry)
             return this;
         }
 
-        public InlineBuilder Formatters(IBuilder<FormatterRegistry>? registry)
+        /// <summary>
+        /// Configures the formatters to be used to extract path values.
+        /// </summary>
+        /// <param name="registry">The registry to be used by the handler</param>
+        public InlineBuilder Formatters(IBuilder<FormatterRegistry> registry)
         {
             _Formatters = registry;
             return this;

Modules/Webservices/Extensions.cs

@@ -1,6 +1,7 @@
 using System.Diagnostics.CodeAnalysis;
 
 using GenHTTP.Api.Infrastructure;
+
 using GenHTTP.Modules.Conversion.Formatters;
 using GenHTTP.Modules.Conversion.Providers;
 using GenHTTP.Modules.Layouting.Provider;
@@ -23,7 +24,8 @@ public static class Extensions
         /// <typeparam name="T">The type of the resource to be added</typeparam>
         /// <param name="path">The path the resource should be available at</param>
         /// <param name="injectors">Optionally the injectors to be used by this service</param>
-        /// <param name="formats">Optionally the formats to be used by this service</param>
+        /// <param name="serializers">Optionally the formats to be used by this service</param>
+        /// <param name="formatters">Optionally the formatters to be used by this service</param>
         public static LayoutBuilder AddService<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] T>(this LayoutBuilder layout, string path, IBuilder<InjectionRegistry>? injectors = null, IBuilder<SerializationRegistry>? serializers = null, IBuilder<FormatterRegistry>? formatters = null) where T : new()
         {
             return layout.Add(path, ServiceResource.From<T>().Configured(injectors, serializers, formatters));
@@ -36,7 +38,8 @@ public static class Extensions
         /// <param name="path">The path the resource should be available at</param>
         /// <param name="instance">The webservice resource instance</param>
         /// <param name="injectors">Optionally the injectors to be used by this service</param>
-        /// <param name="formats">Optionally the formats to be used by this service</param>
+        /// <param name="serializers">Optionally the formats to be used by this service</param>
+        /// <param name="formatters">Optionally the formatters to be used by this service</param>
         public static LayoutBuilder AddService(this LayoutBuilder layout, string path, object instance, IBuilder<InjectionRegistry>? injectors = null, IBuilder<SerializationRegistry>? serializers = null, IBuilder<FormatterRegistry>? formatters = null)
         {
             return layout.Add(path, ServiceResource.From(instance).Configured(injectors, serializers, formatters));

Modules/Webservices/Provider/ServiceResourceBuilder.cs

@@ -47,7 +47,7 @@ public ServiceResourceBuilder Injectors(IBuilder<InjectionRegistry> registry)
             return this;
         }
 
-        public ServiceResourceBuilder Formatters(IBuilder<FormatterRegistry>? registry)
+        public ServiceResourceBuilder Formatters(IBuilder<FormatterRegistry> registry)
         {
             _Formatters = registry;
             return this;