From 50097eb201b3a77507a4806fa16badd005254f1c Mon Sep 17 00:00:00 2001
From: Steve Dunn <steve@dunnhq.com>
Date: Mon, 9 Sep 2024 10:34:56 +0100
Subject: [PATCH] Update documentation

---
 README.md                                    | 222 ++++---------------
 docs/site/Writerside/topics/reference/FAQ.md |  96 ++++----
 2 files changed, 94 insertions(+), 224 deletions(-)

diff --git a/README.md b/README.md
index a87fa4dba5..7a75cd463e 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,9 @@
 ## Give a Star! :star:
 If you like or are using this project please give it a star. Thanks!
       
-Pronounced "Voh Jen"
+Vogen is often mispronounced as Vogen, but it's actually pronounced Vogen:
+
+"Voh Jen"
 
 <audio controls>
   <source src="assets/voh-jen.wav" type="audio/wav">
@@ -37,20 +39,23 @@ The source generator generates strongly typed **domain concepts**. You provide t
 
 ```csharp
 [ValueObject<int>]
-public partial struct CustomerId {
-}
+public partial struct CustomerId;
 ```
 
 ... and Vogen generates source similar to this:
 
 ```csharp
-    public partial struct CustomerId : System.IEquatable<CustomerId>, System.IComparable<CustomerId>, System.IComparable {
+    public partial struct CustomerId : 
+        System.IEquatable<CustomerId>, 
+        System.IComparable<CustomerId>, System.IComparable 
+    {
         private readonly int _value;
 
         public readonly int Value => _value;
 
         public CustomerId() {
-            throw new Vogen.ValueObjectValidationException("Validation skipped by attempting to use the default constructor...");
+            throw new Vogen.ValueObjectValidationException(
+                "Validation skipped by attempting to use the default constructor...");
         }
 
         private CustomerId(int value) => _value = value;
@@ -93,10 +98,10 @@ public void SendInvoice(CustomerId customerId) { ... }
 
 ```csharp
 [ValueObject<decimal>] 
-public partial struct AccountBalance { }
+public partial struct AccountBalance;
 
 [ValueObject(typeof(string))]
-public partial class LegalEntityName { }
+public partial class LegalEntityName;
 ```
 
 The main goal of Vogen is to **ensure the validity of your value objects**, the code analyser helps you to avoid mistakes which 
@@ -108,9 +113,11 @@ could mean that you forget to set a value, so **Vogen doesn't allow you to have
 
 ```csharp
 [ValueObject]
-public partial struct CustomerId {
+public partial struct CustomerId 
+{
     // Vogen deliberately generates this so that you can't create your own:
-    // error CS0111: Type 'CustomerId' already defines a member called 'CustomerId' with the same parameter type
+    // error CS0111: Type 'CustomerId' already defines a member called 'CustomerId' 
+    // with the same parameter type
     public CustomerId() { }
 
     // error VOG008: Cannot have user defined constructors, please use the From method for creation.
@@ -129,7 +136,8 @@ var c = default(CustomerId); // error VOG009: Type 'CustomerId' cannot be constr
 var c = GetCustomerId(); // error VOG010: Type 'CustomerId' cannot be constructed with 'new' as it is prohibited
 
 var c = Activator.CreateInstance<CustomerId>(); // error VOG025: Type 'CustomerId' cannot be constructed via Reflection as it is prohibited.
-var c = Activator.CreateInstance(typeof(CustomerId)); // error VOG025: Type 'MyVo' cannot be constructed via Reflection as it is prohibited
+var c = Activator.CreateInstance(<CustomerId>); // error VOG025: Type 'MyVo' cannot be constructed via Reflection as 
+it is prohibited
 
 // catches lambda expressions
 Func<CustomerId> f = () => default; // error VOG009: Type 'CustomerId' cannot be constructed with default as it is prohibited.
@@ -179,16 +187,15 @@ It's as simple as creating types like this:
 
 ```csharp
 [ValueObject] 
-public partial struct CustomerId { }
+public partial struct CustomerId;
 
 [ValueObject] 
-public partial struct AccountId { }
+public partial struct AccountId;
 
 [ValueObject<decimal>] 
-public partial struct PaymentAmount { }
+public partial struct PaymentAmount;
 ```
 
-
 ## More on Primitive Obsession
 The source generator generates [value objects](https://wiki.c2.com/?ValueObject). value objects help combat Primitive Obsession by wrapping simple primitives such as `int`, `string`, `double` etc. in a strongly-typed type.
 
@@ -286,7 +293,7 @@ public void Process(Person person) {
 We can also specify other instance properties:
 
 ```csharp
-[ValueObject(typeof(float))]
+[ValueObject<float>]
 [Instance("Freezing", 0)]
 [Instance("Boiling", 100)]
 public readonly partial struct Celsius {
@@ -297,7 +304,7 @@ public readonly partial struct Celsius {
 
 ## Configuration
 
-Each value object can have it's own *optional* configuration. Configuration includes:
+Each value object can have its own *optional* configuration. Configuration includes:
 
 * The underlying type
 * Any 'conversions' (Dapper, System.Text.Json, Newtonsoft.Json, etc.) - see [the Integrations page](https://stevedunn.github.io/Vogen/integration.html) in the wiki for more information
@@ -306,7 +313,10 @@ Each value object can have it's own *optional* configuration. Configuration incl
 If any of those above are not specified, then global configuration is inferred. It looks like this:
 
 ```csharp
-[assembly: VogenDefaults(underlyingType: typeof(int), conversions: Conversions.Default, throws: typeof(ValueObjectValidationException))]
+[assembly: VogenDefaults(
+    underlyingType: typeof(int), 
+    conversions: Conversions.Default, 
+    throws: typeof(ValueObjectValidationException))]
 ```
 
 Those again are optional. If they're not specified, then they are defaulted to:
@@ -378,8 +388,8 @@ By default, each VO is decorated with a `TypeConverter` and `System.Text.Json` (
 They are controlled by the `Conversions` enum. The following has serializers for NSJ and STJ:
 
 ```csharp
-[ValueObject(conversions: Conversions.NewtonsoftJson | Conversions.SystemTextJson, underlyingType: typeof(float))]
-public readonly partial struct Celsius { }
+[ValueObject<float>(conversions: Conversions.NewtonsoftJson | Conversions.SystemTextJson)]
+public readonly partial struct Celsius;
 ```
 
 If you don't want any conversions, then specify `Conversions.None`.
@@ -396,6 +406,8 @@ See the examples folder for more information.
 
 ## FAQ
 
+What follows is an excerpt from the [full FAQ page in the Wiki](https://stevedunn.github.io/Vogen/faq.html).
+
 ### Is there a Wiki for this project?
 
 Yes, it's here: https://stevedunn.github.io/Vogen/vogen.html
@@ -423,16 +435,6 @@ If you're using the generator in a .NET Framework project and using the old styl
 
 ```
 
-### Does it support C# 11 features?
-This is primarily a source generator. The source it generates is mostly C# 6 for compatibility. But if you use features from a later language version, for instance `records` from C# 9, then it will also generate records.
-
-Source generation is driven by attributes, and, if you're using .NET 7 or above, the generic version of the `ValueObject` attribute is exposed:
-
-```csharp
-[ValueObject<int>]
-public partial struct Age { }
-```
-
 ### Why are they called 'value objects'?
 
 The term value object represents a small object who's equality is based on value and not identity. From [Wikipedia](https://en.wikipedia.org/wiki/Value_object)
@@ -443,29 +445,6 @@ In DDD, a value object is (again, from [Wikipedia](https://en.wikipedia.org/wiki
 
 >  _... a value object is an immutable object that contains attributes but has no conceptual identity_
 
-### How can I view the code that is generated?
-
-Add this to your `.csproj` file:
-
-```xml
-<PropertyGroup>
-    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
-    <CompilerGeneratedFilesOutputPath>Generated</CompilerGeneratedFilesOutputPath>
-</PropertyGroup>
-
-<ItemGroup>
-    <Compile Remove="Generated/*/**/*.cs" />
-</ItemGroup>
-```
-
-Then, you can view the generated files in the `Generated` folder. In Visual Studio, you need to select 'Show all files' in the Solution Explorer window:
-
-![the solution explorer window showing the 'show all files' option](./docs/img/20220425061514.png)
-
-Here's an example from the included `Samples` project:
-
-![the solution explorer window showing generated files](docs/img/20220425061733.png)
-
 ### Why can't I just use `public record struct CustomerId(int Value);`?
 
 That doesn't give you validation. To validate `Value`, you can't use the shorthand syntax (Primary Constructor). So you'd need to do:
@@ -499,6 +478,9 @@ Yes. By default, each VO is decorated with a `TypeConverter` and `System.Text.Js
 * Dapper
 * EFCore
 * LINQ to DB
+* MongoDB/BSON
+* Orleans
+* ServiceStack.Text
 
 ### Can I use them in EFCore?
 
@@ -540,7 +522,7 @@ Concretely: *"When 5 things need to change, Shalloway will find at most, 4 of th
 If you add further constructors, then you will get a compilation error from the code generator, e.g.
 
 ```csharp
-[ValueObject(typeof(int))]
+[ValueObject<int>)]
 public partial struct CustomerId {
     // Vogen already generates this as a private constructor:
     // error CS0111: Type 'CustomerId' already defines a member called 'CustomerId' with the same parameter type
@@ -555,119 +537,6 @@ public partial struct CustomerId {
 
 You *could*, but you'd get compiler warning [CS0282-There is no defined ordering between fields in multiple declarations of partial class or struct 'type'](https://docs.microsoft.com/en-us/dotnet/csharp/misc/cs0282)
 
-### Why are there, by default, no implicit conversions to and from the primitive types that are being wrapped?
-
-Implicit operators can be useful, but for value objects, they can confuse things. Take the following code **without** any implicit conversions:
-
-```csharp
-Age age1 = Age.From(1);
-OsVersion osVersion = OsVersion.From(1);
-
-Console.WriteLine(age1 == osVersion); // won't compile! \o/
-```
-
-That makes perfect sense. But adding in an implicit operator **from** `Age` **to** `int`, and it does compile!
-
-`Console.WriteLine(age1 == osVersion); // TRUE! (◎_◎;)`
-
-If we remove that implicit operator and replace it with an implicit operator **from** `int` **to** `Age`, it no longer compiles, which is great (we've got type safety back), but we end up [violating the rules of implicit operators](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/user-defined-conversion-operators):
-
-> Predefined C# implicit conversions always succeed and never throw an exception. User-defined implicit conversions should behave in that way as well. If a custom conversion can throw an exception or lose information, define it as an explicit conversion
-
-In my research, I read some other opinions, and noted that the guidelines listed in [this answer](https://softwareengineering.stackexchange.com/a/284377/30906) say:
-
-* If the conversion can throw an `InvalidCast` exception, then it shouldn't be implicit.
-* If the conversion causes a heap allocation each time it is performed, then it shouldn't be implicit.
-
-Which is interesting - Vogen _wouldn't_ throw an `InvalidCastException` (only an `ValueObjectValidationException`).  Also, for `struct`s, we _wouldn't_ create a heap allocation.
-
-But since users of Vogen can declare a value object as a `class` **or** `struct`, then we wouldn't want implicit operators (from `primitive` => `ValueObject`) for just `structs` and not `class`es.
-
-### Can you opt-in to implicit conversions?
-
-Yes, by specifying the `toPrimitiveCasting` and `fromPrimitiveCasting` in either local or global config.
-By default, explicit operators are generated for both. Bear in mind that you can only define implicit _or_ explicit operators;
-you can't have both.
-
-Also, bear in mind that ease of use can cause confusions. Let's say there's a type like this (and imagine that there's implicit conversions to `Age` and to `int`'):
-
-```csharp
-[ValueObject(typeof(int))]
-public readonly partial struct Age {
-    public static Validation Validate(int n) => n >= 0 ? Validation.Ok : Validation.Invalid("Must be zero or more");
-}
-```
-
-That says that `Age` instances can never be negative.  So you would probably expect the following to throw, but it doesn't:
-
-```csharp
-var age20 = Age.From(20);
-var age10 = age20 / 2;
-++age10;
-age10 -= 12; // bang - goes negative??
-```
-
-The implicit cast in `var age10 = age20 / 2` results in an `int` and not an `Age`. Changing it to `Age age10 = age20 / 2` fixes it. But this does go to show that it can be confusing.
-
-### Why is there no interface?
-
-> _If I'm using a library that uses Vogen, I'd like to easily tell if the type is just a primitive wrapper or not by the fact that it implements an interface, such as `IValidated<T>`_
-
-Just like primitives have no interfaces, there's no need to have interfaces on value objects. The receiver that takes a `CustomerId` knows that it's a value object.  If it were instead to take an `IValidated<int>`, then it wouldn't have any more information; you'd still have to know to call `Value` to get the value.
-
-It might also relax type safety. Without the interface, we have signatures such as this:
-
-```csharp
-public void SomSomething(CustomerId customerId, SupplierId supplierId, ProductId productId);
-```
-
-... but with the interface, we _could_ have signatures such as this:
-
-```csharp
-public void SomSomething(IValidate<int> customerId, IValidated<int> supplierId, IValidated<int> productId);
-```
-
-So, callers could mess things up by calling `DoSomething(productId, supplierId, customerId)`)
-
-There would also be no need to know if it's validated, as, if it's in your domain, **it's valid** (there's no way to manually create invalid instances).  And with that said, there would also be no point in exposing the 'Validate' method via the interface because validation is done at creation.
-
-### Can I represent special values
-
-Yes. You might want to represent special values for things like invalid or unspecified instances, e.g.
-
-```csharp
-/*
-* Instances are the only way to avoid validation, so we can create instances
-* that nobody else can. This is useful for creating special instances
-* that represent concepts such as 'invalid' and 'unspecified'.
-*/
-[ValueObject]
-[Instance("Unspecified", -1)]
-[Instance("Invalid", -2)]
-public readonly partial struct Age
-{
-    private static Validation Validate(int value) =>
-        value > 0 ? Validation.Ok : Validation.Invalid("Must be greater than zero.");
-}
-```
-
-You can then use default values when using these types, e.g.
-
-```csharp
-public class Person {
-    public Age Age { get; set; } = Age.Unspecified
-}
-```
-
-... and if you take an Age, you can compare it to an instance that is invalid/unspecified
-
-```csharp
-public void CanEnter(Age age) {
-    if(age == Age.Unspecified || age == Age.Invalid) throw CannotEnterException("Age not specified or is invalid")
-    return age < 17;
-}
-```
-
 ### Can I normalize the value when a VO is created?
 I'd like normalize/sanitize the values used, for example, trimming the input. Is this possible?
 
@@ -678,21 +547,6 @@ Yes, add NormalizeInput method, e.g.
 See [wiki](https://stevedunn.github.io/Vogen/normalization.html) for more information.
 
 
-### Can I create custom value object attributes with my own defaults?
-
-Yes, but (at the moment) it requires that you put your defaults in your attribute's constructor - not in the call to 
-the base class' constructor (see [this comment](https://github.com/SteveDunn/Vogen/pull/321#issuecomment-1399324832)).
-
-```csharp
-public class CustomValueObjectAttribute : ValueObjectAttribute<long>
-{
-    // This attribute will default to having both the default conversions and EF Core type conversions
-    public CustomValueObjectAttribute(Conversions conversions = Conversions.Default | Conversions.EfCoreValueConverter) { }
-}
-```
-
-NOTE: *custom attributes must extend a ValueObjectAttribute class; you cannot layer custom attributes on top of each other*
-
 ### Why isn't this concept part of the C# language?
 
 It would be great if it was, but it's not currently. I [wrote an article about it](https://dunnhq.com/posts/2022/non-defaultable-value-types/), but in summary, there is a [long-standing language proposal](https://github.com/dotnet/csharplang/issues/146) focusing on non-defaultable value types.
@@ -741,10 +595,10 @@ Any type can be wrapped. Serialisation and type conversions have implementations
 For other types, a generic type conversion and serializer is applied. If you are supplying your own converters for type conversion and serialization, then specify `None` for converters and decorate your type with attributes for your own types, e.g.
 
 ```csharp
-[ValueObject(typeof(SpecialPrimitive), conversions: Conversions.None)]
+[ValueObject<SpecialPrimitive>(conversions: Conversions.None)]
 [System.Text.Json.Serialization.JsonConverter(typeof(SpecialPrimitiveJsonConverter))]
 [System.ComponentModel.TypeConverter(typeof(SpecialPrimitiveTypeConverter))]
-public partial struct SpecialMeasurement { }
+public partial struct SpecialMeasurement;
 ```
 
 ### Can I get it to throw my own exception?
@@ -762,7 +616,7 @@ Linq2DB 4.0 or greater supports `DateOnly` and `TimeOnly`. Vogen generates value
 Yes. Add a dependency to protobuf-net and set a surrogate attribute:
 
 ```csharp
-[ValueObject(typeof(string))]
+[ValueObject<string>]
 [ProtoContract(Surrogate = typeof(string))]
 public partial class BoxId {
 //...
diff --git a/docs/site/Writerside/topics/reference/FAQ.md b/docs/site/Writerside/topics/reference/FAQ.md
index e69e9cccf3..2dd9312e30 100644
--- a/docs/site/Writerside/topics/reference/FAQ.md
+++ b/docs/site/Writerside/topics/reference/FAQ.md
@@ -40,7 +40,7 @@ _I'd like to be able to identify types that are generated by Vogen so that I can
 
 This is described in [this how-to page](efcore-tips.md)
 
-### What versions of .NET are supported?
+## What versions of .NET are supported?
 
 The source generator is .NET Standard 2.0. The code it generates supports all C# language versions from 6.0 and onwards
 
@@ -66,7 +66,7 @@ If you're using the generator in a .NET Framework project and using the old styl
     </Configuration>
 ```
 
-### Does it support C# 11 features?
+## Does it support C# 11 features?
 This is primarily a source generator. The source it generates is mostly C# 6 for compatibility. But if you use features from a later language version, for instance `records` from C# 9, then it will also generate records.
 
 Source generation is driven by attributes, and, if you're using .NET 7 or above, the generic version of the `ValueObject` attribute is exposed:
@@ -76,7 +76,7 @@ Source generation is driven by attributes, and, if you're using .NET 7 or above,
 public partial struct Age { }
 ```
 
-### Why are they called 'Value Objects'?
+## Why are they called 'Value Objects'?
 
 The term Value Object represents a small object whose equality is based on value and not identity. From [Wikipedia](https://en.wikipedia.org/wiki/Value_object)
 
@@ -86,7 +86,7 @@ In DDD, a Value Object is (again, from [Wikipedia](https://en.wikipedia.org/wiki
 
 >  _... a Value Object is an immutable object that contains attributes but has no conceptual identity_
 
-### How can I view the code that is generated?
+## How can I view the code that is generated?
 
 Add this to your `.csproj` file:
 
@@ -111,7 +111,7 @@ Here's an example from the included `Samples` project:
 
 ![the solution explorer window showing generated files](20220425061733.png)
 
-### Why can't I just use `public record struct CustomerId(int Value);`?
+## Why can't I just use `public record struct CustomerId(int Value);`?
 
 That doesn't give you validation. To validate `Value`, you can't use the shorthand syntax (Primary Constructor). 
 So you'd need to do:
@@ -138,7 +138,7 @@ CustomerId c = default;
 var c2 = default(CustomerId);
 ```
 
-### Can I serialize and deserialize them?
+## Can I serialize and deserialize them?
 
 Yes. By default, each VO is decorated with a `TypeConverter` and `System.Text.Json` (STJ) serializer. There are other converters/serializers for:
 
@@ -146,8 +146,12 @@ Yes. By default, each VO is decorated with a `TypeConverter` and `System.Text.Js
 * Dapper
 * EFCore
 * LINQ to DB
+* MongoDB/BSON
+* Orleans
+* ServiceStack.Text
+* Protobuf
 
-### Can I use them in EFCore?
+## Can I use them in EFCore?
 
 Yes, although there are certain considerations. [Please see the EFCore page on the Wiki](https://github.com/SteveDunn/Vogen/wiki/Value-Objects-in-EFCore),
 but the TL;DR is:
@@ -175,15 +179,15 @@ You could, but to ensure consistency throughout your domain, you'd have to **val
 
 Concretely: *"When 5 things need to change, Shalloway will find at most, 4 of these things."*
 
-### If my VO is a `struct`, can I prohibit using `CustomerId customerId = default(CustomerId);`?
+## If my VO is a `struct`, can I prohibit using `CustomerId customerId = default(CustomerId);`?
 
 **Yes**. The analyzer generates a compilation error.
 
-### If my VO is a `struct`, can I prohibit using `CustomerId customerId = new(CustomerId);`?
+## If my VO is a `struct`, can I prohibit using `CustomerId customerId = new(CustomerId);`?
 
 **Yes**. The analyzer generates a compilation error.
 
-### If my VO is a struct, can I have my own constructor?
+## If my VO is a struct, can I have my own constructor?
 
 **No**. The parameter-less constructor is generated automatically, and the constructor that takes the underlying value is also generated automatically.
 
@@ -203,29 +207,40 @@ public partial struct CustomerId {
 }
 ```
 
-### If my VO is a struct, can I have my own fields?
+## If my VO is a struct, can I have my own fields?
 
 You _could_, but you'd get compiler warning [CS0282-There is no defined ordering between fields in multiple declarations of partial class or struct 'type'](https://docs.microsoft.com/en-us/dotnet/csharp/misc/cs0282)
 
-### Why are there, by default, no implicit conversions to and from the primitive types that are being wrapped?
+## Why are there, by default, no implicit conversions to and from the primitive types that are being wrapped?
 
-Implicit operators can be useful, but for Value Objects, they can confuse things. Take the following code **without** any implicit conversions:
+Implicit operators can be useful, but for Value Objects, they can confuse things. Take the following code **with** implicit conversions:
 
 ```c#
-Age age1 = Age.From(1);
-OsVersion osVersion = OsVersion.From(1);
+Age age = Age.From(1);
+int anInt = age;
+Print(anInt);
 
-Console.WriteLine(age1 == osVersion); // won't compile! \o/
-```
+void Print(OsVersion osVersion) => Console.WriteLine(osVersion);
+
+[ValueObject(
+  fromPrimitiveCasting: CastOperator.Implicit, 
+  toPrimitiveCasting: CastOperator.Implicit)]
+public partial class Age;
 
-That makes perfect sense. But adding in an implicit operator **from** `Age` **to** `int`, and it does compile!
+[ValueObject(
+  fromPrimitiveCasting: CastOperator.Implicit, 
+  toPrimitiveCasting: CastOperator.Implicit)]
+public readonly partial struct OsVersion;
+```
 
-`Console.WriteLine(age1 == osVersion); // TRUE! (◎_◎;)`
+We can see that we lose type-safety. An `Age` is implicitly an int, and an `OsVersion` is implicitly an int.
 
-If we remove that implicit operator and replace it with an implicit operator **from** `int` **to** `Age`, it no longer compiles, which is great (we've got type safety back), but we end up [violating the rules of implicit operators](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/user-defined-conversion-operators):
+There are also issues with validation that [violates the rules of implicit operators](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/user-defined-conversion-operators), which is:
 
 > Predefined C# implicit conversions always succeed and never throw an exception. User-defined implicit conversions should behave in that way as well. If a custom conversion can throw an exception or lose information, define it as an explicit conversion
 
+But a primitive cast to a value object might not always succeed due to validation.
+
 In my research, I read some other opinions, and noted that the guidelines listed in [this answer](https://softwareengineering.stackexchange.com/a/284377/30906) say:
 
 * If the conversion can throw an `InvalidCast` exception, then it shouldn't be implicit.
@@ -235,7 +250,7 @@ Which is interesting—Vogen _wouldn't_ throw an `InvalidCastException` (only an
 
 But since users of Vogen can declare a Value Object as a `class` **or** `struct`, then we wouldn't want implicit operators (from `primitive` => `ValueObject`) for just `structs` and not `class`es.
 
-### Can you opt in to implicit conversions?
+## Can you opt in to implicit conversions?
 
 Yes, by specifying the `toPrimitiveCasting` and `fromPrimitiveCasting` in either local or global config.
 By default, explicit operators are generated for both. Bear in mind that you can only define implicit _or_ explicit operators;
@@ -263,7 +278,7 @@ age10 -= 12; // bang - goes negative??
 
 The implicit cast in `var age10 = age20 / 2` results in an `int` and not an `Age`. Changing it to `Age age10 = age20 / 2` fixes it. But this does go to show that it can be confusing.
 
-### Why is there no interface?
+## Why is there no interface?
 
 > _If I'm using a library that uses Vogen, I'd like to easily tell if the type is just a primitive wrapper or not by the fact that it implements an interface, such as `IValidated<T>`_
 
@@ -296,7 +311,7 @@ There would also be no need to know if it's validated, as, if it's in your domai
 
 Having said that, outside of the domain, it can be useful to have an interface. The [Guids tutorial](how-to-guides.topic) describes how to generate the interface and when it's useful to do so. 
 
-### Can I represent special values
+## Can I represent special values
 
 Yes. You might want to represent special values for things like _invalid_ or _unspecified_ instances, e.g.
 
@@ -340,7 +355,7 @@ public void CanEnter(Age age) {
 }
 ```
 
-### Can I normalize the value when a VO is created?
+## Can I normalize the value when a VO is created?
 I'd like to normalize/sanitize the values used, for example, trimming the input. Is this possible?
 
 Yes, add NormalizeInput method, e.g.
@@ -350,7 +365,7 @@ Yes, add NormalizeInput method, e.g.
 See [the how-to page](NormalizationHowTo.md) for more information.
 
 
-### Can I create custom Value Object attributes with my own defaults?
+## Can I create custom Value Object attributes with my own defaults?
 
 No, it used to be possible, but it impacts the performance of Vogen.
 A much better way is 
@@ -358,7 +373,7 @@ to use [type alias feature](https://learn.microsoft.com/en-us/dotnet/csharp/lang
 
 NOTE: *custom attributes must extend a ValueObjectAttribute class; you cannot layer custom attributes on top of each other*
 
-### Why isn't this concept part of the C# language?
+## Why isn't this concept part of the C# language?
 
 It would be great if it was, but it's not there currently. I [wrote an article about it](https://dunnhq.com/posts/2022/non-defaultable-value-types/), but in summary, there is a [long-standing language proposal](https://github.com/dotnet/csharplang/issues/146) focusing on non-defaultable value types.
 Having non-defaultable value types is a great first step, but it would also be handy to have something in the language to enforce validation.
@@ -366,11 +381,11 @@ So I added a [language proposal for invariant records](https://github.com/dotnet
 
 One of the responses in the proposal says that the language team decided that validation policies should not be part of C#, but provided by source generators.
 
-### How do I run the benchmarks?
+## How do I run the benchmarks?
 
 `dotnet run -c Release -- --job short --framework net6.0 --filter *`
 
-### Why do I get a build error when running `.\Build.ps1`?
+## Why do I get a build error when running `.\Build.ps1`?
 
 You might see this:
 ```
@@ -381,7 +396,7 @@ You might see this:
 
 To get around this, run `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass`
 
-### What alternatives are there?
+## What alternatives are there?
 
 [StronglyTypedId](https://github.com/andrewlock/StronglyTypedId)
 This is focused more on IDs. Vogen is focused more on 'Domain Concepts' and the constraints associated with those concepts.
@@ -395,7 +410,7 @@ Similar to StringlyTyped - non-source-generated and no analyzers. This is also m
 [ValueObjectGenerator](https://github.com/RyotaMurohoshi/ValueObjectGenerator)
 Similar to Vogen, but less focused on validation and no code analyzer.
 
-### What primitive types are supported?
+## What primitive types are supported?
 
 Any type can be wrapped. Serialisation and type conversions have implementations for:
 * string
@@ -428,7 +443,7 @@ conversion and serialization, then specify `None` for converters and decorate yo
 public partial struct SpecialMeasurement;
 ```
 
-### I've made a change that means the 'Snapshot' tests are expectedly failing in the build—what do I do?
+## I've made a change that means the 'Snapshot' tests are expectedly failing in the build—what do I do?
 
 Vogen uses a combination of unit tests, in-memory compilation tests, and snapshot tests. The snapshot tests are used
 to compare the output of the source generators to the expected output stored on disk.
@@ -448,30 +463,30 @@ folder and treats everything generated as the new baseline for future comparison
 This will mean there are potentially **thousands** of changed files that will end up in the commit, 
 but it's expected and unavoidable.
 
-### How do I debug the source generator?
+## How do I debug the source generator?
 
 The easiest way is to debug the SnapshotTests. Put a breakpoint in the code, and then debug a test somewhere.
 
 To debug an analyzer, select or write a test in the AnalyzerTests. There are tests that exercise the various analyzers and code-fixers.
 
-### How do I run the tests that actually use the source generator?
+## How do I run the tests that actually use the source generator?
 
 It is challenging to run tests that _use_ the source generator in the same project **as** the source generator, so there
 is a separate solution for this. It's called `Consumers.sln`. What happens is that `build.ps1` builds the generator, runs
 the tests, and creates the NuGet package _in a private local folder_. The package is version `999.9.xxx` and the consumer
 references the latest version. The consumer can then _really_ use the source generator, just like anything else.
 
-### Can I get it to throw my own exception?
+## Can I get it to throw my own exception?
 
 Yes, by specifying the exception type in either the `ValueObject` attribute, or globally, with `VogenConfiguration`.
 
-### I get an error from Linq2DB when I use a ValueObject that wraps a `TimeOnly` saying that `DateTime` cannot be converted to `TimeOnly`—what should I do?
+## I get an error from Linq2DB when I use a ValueObject that wraps a `TimeOnly` saying that `DateTime` cannot be converted to `TimeOnly`—what should I do?
 
 Linq2DB 4.0 or greater supports `DateOnly` and `TimeOnly`. Vogen generates value converters for Linq2DB; for `DateOnly`, it just works, but for `TimeOnly, you need to add this to your application:
 
 `MappingSchema.Default.SetConverter<DateTime, TimeOnly>(dt => TimeOnly.FromDateTime(dt));`
 
-### Can I use protobuf-net?
+## Can I use protobuf-net?
 
 Yes. Add a dependency to protobuf-net and set a surrogate attribute:
 
@@ -486,7 +501,7 @@ for other applications from C#, proto files will include the `Surrogate` type as
 
 _thank you to [@DomasM](https://github.com/DomasM) for this information_.
 
-### Can I have a factory method for value objects that wrap GUIDs?
+## Can I have a factory method for value objects that wrap GUIDs?
 
 Yes, use the `Customizations.AddFactoryMethodForGuids` in the global config attribute, e.g.
 
@@ -505,7 +520,7 @@ var newCustomerId = CustomerId.FromNewGuid();
 > To customize the generation of Guids, please see [this tutorial](Working-with-IDs.md)
 > 
 
-### Can I use value objects instead of primitives as parameters in Blazor pages and components?
+## Can I use value objects instead of primitives as parameters in Blazor pages and components?
 
 You can, but it's not straightforward.
 Blazor, unlike ASP.NET Core, doesn't consider type converters.
@@ -528,7 +543,7 @@ There are two solutions:
         ...
 ```
 
-### Are value objects any bigger than the primitives that they wrap?
+## Are value objects any bigger than the primitives that they wrap?
 They are by default, but they can be configured so that they're not.
 
 They're bigger because Vogen generates code that stores a field named `_isInitialized`. This
@@ -560,4 +575,5 @@ If it is important that your debug builds have the same size value objects as yo
 
 ```c#
 [assembly: VogenDefaults(disableStackTraceRecordingInDebug: true)]
-```
\ No newline at end of file
+```
+