docs: add more documentation pages

README.md

@@ -15,23 +15,30 @@ X10D (pronounced *extend*), is a .NET package that provides extension methods fo
 *(I'm also [dogfooding](https://www.pcmag.com/encyclopedia/term/dogfooding) this library, so there's that.)*
 
 ## Installation
+
 ### NuGet installation
+
 ```ps
 Install-Package X10D -Version 4.0.0
 ```
 
 ### Manual installation
+
 Download the [latest release](https://github.com/oliverbooth/X10D/releases/latest) from this repository and adding a direct assembly reference for your chosen platform.
 
 ### Unity installation
+
 For the Unity installation guide, refer to the [README.md in X10D.Unity](X10D.Unity/README.md).
 
-## Features
+## Documentation
-I'm planning on writing complete and extensive documentation in the near future. As of this time, feel free to browse the source or the API using your favourite IDE.
+
-For those familiar with the 2.6.0 API, please read [CHANGELOG.md](CHANGELOG.md) for a complete list of changes. **3.0.0 is a major release and introduces many breaking changes.**
+Documentation and the API reference is available at https://oliverbooth.github.io/X10D/index.html. *I'm sorry this took
+so long to get up and running. DocFX will be the death of me.*
 
 ## Contributing
+
 Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
+
 X10D is released under the MIT License. See [here](https://github.com/oliverbooth/X10D/blob/main/LICENSE.md) for more details.

docfx_project/articles/intro.md

@@ -1 +1,86 @@
-# Add your introductions here!
+## X10D
+X10D (pronounced *extend*), is a .NET package that provides extension methods for numerous types. The purpose of this library is to simplify a codebase by reducing the need for repeated code when performing common operations. Simplify your codebase. Take advantage of .NET. Use extension methods.
+
+*(I'm also [dogfooding](https://www.pcmag.com/encyclopedia/term/dogfooding) this library, so there's that.)*
+
+### What are extension methods?
+
+Extension methods are a clever .NET feature that augment existing types with new functionality. They are defined as
+static methods in a static class, and are called as if they were instance methods on the type they are extending. Take,
+for example, the following code:
+
+```csharp
+public static class Program
+{
+    public static void Main()
+    {
+        string str = "Hello, world!";
+        Console.WriteLine(str.Reverse());
+    }
+}
+
+public static class StringExtensions
+{
+    public static string Reverse(this string str)
+    {
+        char[] chars = str.ToCharArray();
+        Array.Reverse(chars);
+        return new string(chars);
+    }
+}
+```
+
+This will print `!dlrow ,olleH` to the console. The `Reverse` method is defined in the `StringExtensions` class, yet is
+called as if it were an instance method on the `str` variable, even though it's not.
+
+### Why use extension methods?
+
+Extension methods were introduced when LINQ was added to .NET. LINQ is a set of extension methods that provide a way to
+query, filter, and transform data. If you were to access LINQ's methods statically, you would have to write code like
+this:
+
+```csharp
+public static class Program
+{
+    public static void Main()
+    {
+        int[] numbers = { 1, 2, 3, 4, 5 };
+        IEnumerable<int> evenNumbers = Enumerable.Where(numbers, x => x % 2 == 0);
+        IEnumerable<int> doubledNumbers = Enumerable.Select(evenNumbers, x => x * 2);
+        int sum = Enumerable.Sum(doubledNumbers);
+        Console.WriteLine(sum);
+    }
+}
+```
+
+And if you wanted to one-line this, you'd have to write this:
+
+```csharp
+public static class Program
+{
+    public static void Main()
+    {
+        int[] numbers = { 1, 2, 3, 4, 5 };
+        Console.WriteLine(Enumerable.Sum(Enumerable.Select(Enumerable.Where(numbers, x => x % 2 == 0), x => x * 2)));
+    }
+}
+```
+
+This is a lot of code to write, and it's not very readable. The nested method calls make it incredibly difficult to
+follow. However, because LINQ is implemented as extension methods, you can write the following code instead:
+
+```csharp
+public static class Program
+{
+    public static void Main()
+    {
+        int[] numbers = { 1, 2, 3, 4, 5 };
+        Console.WriteLine(numbers.Where(x => x % 2 == 0).Select(x => x * 2).Sum());
+    }
+}
+```
+
+Because the methods are called as if they were instance methods on `IEnumerable<T>`, they can be chained together,
+making the code much more readable.
+
+X10D aims to provide these same benefits as LINQ, but for dozens of other types and for countless other use cases.

docfx_project/articles/migration-from-3.x.x.md

@@ -0,0 +1,52 @@
+# Migration from 3.x.x
+
+X10D 4.0.0 is a major release that introduces breaking changes. This document will help you migrate your code from 3.x.x
+to 4.0.0.
+
+## Removed APIs
+
+### X10D.DSharpPlus library
+
+The `X10D.DSharpPlus` library has been removed. This library was used to provide extension methods for the DSharpPlus
+wrapper library. However, I have since moved to using a different library, and as such, I feel it is no longer in the
+scope of X10D or in my best interest to maintain it. The library will remain available on NuGet until DSharpPlus release
+5.0.0 as stable, and X10D.DSharpPlus will NOT be part of X10D 4.0.0. I'm sorry for any inconvenience this may cause.
+
+### `Endianness` enum
+
+The `Endianness` enum was used to specify the endianness of data when reading or writing to a stream. This was causing
+some clutter, and makes it harder to develop X10D, so it was removed. In its stead, any method which accepted an
+`Endianness` parameter now has two overloads: one for big-endian, and one for little-endian. For example, the following
+code:
+
+```csharp
+someStream.Write(12345, Endianness.BigEndian);
+
+// or
+
+Span<byte> buffer = stackalloc byte[4];
+12345.TryWriteBytes(buffer, Endianness.BigEndian);
+```
+
+would now be written as:
+
+```csharp
+someStream.WriteBigEndian(12345);
+
+// or
+
+Span<byte> buffer = stackalloc byte[4];
+12345.TryWriteLittleEndianBytes(buffer);
+```
+
+### `IEnumerable<T>.ConcatOne(T)` extension method
+
+The `IEnumerable<T>.ConcatOne` extension method was used to concatenate a single item to an enumerable. At the time, I
+was unaware of the `Enumerable.Append` method, which does the same thing. As such, `ConcatOne` has been removed. There
+is no migration path for this, as the built in `Append` method from LINQ is a drop-in replacement.
+
+## Exception Changes
+
+If you were previously catching TypeInitializationException when calling `Stream.GetHash<>` or `Stream.TryWriteHash<>`,
+you will now need to catch a ArgumentException instead. The justification for this change is that ArgumentException is
+more general, and more easily understood by developers.

docfx_project/articles/toc.yml

@@ -1,2 +1,4 @@
 - name: Introduction
   href: intro.md
+- name: Migration from 3.x.x
+  href: migration-from-3.x.x.md