Add README.

Author: cwize1

BitSerialization.PerfTests/BitSerializerBenchmark.cs

@@ -5,7 +5,7 @@
 using BenchmarkDotNet.Attributes;
 using BitSerialization.Common;
 using BitSerialization.Reflection.OnTheFly;
-using BitSerialization.Reflection.PreCalculated;
+using BitSerialization.Reflection.Precalculated;
 using System;
 using System.Runtime.InteropServices;
 
@@ -94,7 +94,7 @@ public void OnTheFly()
         }
 
         [Benchmark]
-        public void PreCalculated()
+        public void Precalculated()
         {
             byte[] output = new byte[_DataSerializationSize];
             BitSerializer<Struct3>.Serialize(output, _Data);

BitSerialization.Reflection/PreCalculated/BitSerializerT.cs

@@ -1,13 +1,13 @@
 using BitSerialization.Common;
-using BitSerialization.Reflection.PreCalculated.Implementation;
+using BitSerialization.Reflection.Precalculated.Implementation;
 using BitSerialization.Reflection.Utilities;
 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Reflection;
 using System.Runtime.CompilerServices;
 
-namespace BitSerialization.Reflection.PreCalculated
+namespace BitSerialization.Reflection.Precalculated
 {
     public static class BitSerializer<T>
         where T : struct

BitSerialization.Reflection/PreCalculated/Implementation/BitSerializerArray.cs

@@ -7,7 +7,7 @@
 using System.Collections.Generic;
 using System.Reflection;
 
-namespace BitSerialization.Reflection.PreCalculated.Implementation
+namespace BitSerialization.Reflection.Precalculated.Implementation
 {
     internal abstract class BitSerializerArray<T>
         where T : struct

BitSerialization.Reflection/PreCalculated/Implementation/BitSerializerPrimitiveArrays.cs

@@ -5,7 +5,7 @@
 using BitSerialization.Common;
 using System;
 
-namespace BitSerialization.Reflection.PreCalculated.Implementation
+namespace BitSerialization.Reflection.Precalculated.Implementation
 {
     internal sealed class BitSerializerUInt8Array<T> :
         BitSerializerArray<T>

BitSerialization.Reflection/PreCalculated/Implementation/BitSerializerPrimitives.cs

@@ -9,7 +9,7 @@
 using System.Reflection;
 using System.Runtime.CompilerServices;
 
-namespace BitSerialization.Reflection.PreCalculated.Implementation
+namespace BitSerialization.Reflection.Precalculated.Implementation
 {
     internal static class BitSerializerPrimitives
     {

BitSerialization.Reflection/PreCalculated/Implementation/BitSerializerStructArray.cs

@@ -5,7 +5,7 @@
 using BitSerialization.Common;
 using System;
 
-namespace BitSerialization.Reflection.PreCalculated.Implementation
+namespace BitSerialization.Reflection.Precalculated.Implementation
 {
     internal sealed class BitSerializerStructArray<T> :
         BitSerializerArray<T>

BitSerialization.Reflection/PreCalculated/Implementation/FieldSerializationData.cs

@@ -5,7 +5,7 @@
 using System;
 using System.Reflection;
 
-namespace BitSerialization.Reflection.PreCalculated.Implementation
+namespace BitSerialization.Reflection.Precalculated.Implementation
 {
     // Function type for deserializing a field on an object.
     // Note: The FieldInfo value is passed into this function to allow the JIT-compiler to optimize the FieldInfo.SetValue call

BitSerialization.Tests/BitSerializerTests.cs

@@ -4,7 +4,7 @@
 
 using BitSerialization.Common;
 using BitSerialization.Reflection.OnTheFly;
-using BitSerialization.Reflection.PreCalculated;
+using BitSerialization.Reflection.Precalculated;
 using KellermanSoftware.CompareNetObjects;
 using System;
 using System.Runtime.InteropServices;

README.md

@@ -0,0 +1,32 @@
+# BitSerialization library
+
+> **WARNING**: This code is experimental. Use at your own risk.
+
+A .Net data serialization/deserialization library that assits with communicating with hardware that uses a binary protocol.
+
+## Overview
+
+When communicating with certain types hardware, usually over some kind of serial port, it is not uncommon for the hardware's API to be specified as message frames where the message's payload is made up of a sequence of integers of various sizes.
+
+This library allows the message payload's structure to be specified as a `class` or `struct` and handles the the serialization and deserialization automagically using reflection.
+
+The following types can be used within a message format:
+
+  1. Integer types (e.g. `byte`, `int`, etc.)
+  2. Enum types.
+  3. Other `struct` and `class` types.
+  4. Arrays of #1, #2 and #3.
+
+## Why not use .Net's inbuilt data marshalling (p/invoke)?
+
+.Net's data marshalling API (e.g. the [Marshal class](https://docs.microsoft.com/en-us/dotnet/api/system.runtime.interopservices.marshal)) is intended to be used when communicating with C-style APIs. This includes correctly handling padding between variables to ensure correct type alignment. In addition, it will only ever use the system's endianess when reading and writing integers. However, hardware APIs generally don't include alignment padding to save space and usually require a specific endianness to be used.
+
+## Three implementations
+
+This library includes three different implementations.
+
+  1. **On the fly**: This implementation looks up the type information using reflection every time a serialization or derserialization is requested. This is the simplest implementation. Though it is also the slowest.
+
+  2. **Precalculated**: This implementation looks up the type information using reflection a single time and then stores the steps required to serialize and deserialize the type. This implementation is rather complex (due to its "clever" use of generics). But it is substantially faster than the 'on the fly' implementation.
+
+  3. **Source generators**: This implementation uses the new [C# source generators](https://devblogs.microsoft.com/dotnet/introducing-c-source-generators/) feature that is currently available in the preview version of .Net. Its implementation is slightly more complicated than the 'on the fly' implementation. Though it is substantially faster than both the 'precalculated' and 'on the fly' implementations.