Tons of docs updates

src/NexusMods.EventSourcing.Abstractions/ACollectionAttribute.cs

@@ -6,18 +6,29 @@
 
 namespace NexusMods.EventSourcing.Abstractions;
 
+/// <summary>
+/// Abstract base class for an attribute that is a collection of entities.
+/// </summary>
+/// <param name="name"></param>
+/// <typeparam name="TOwner"></typeparam>
+/// <typeparam name="TType"></typeparam>
 public class ACollectionAttribute<TOwner, TType>(string name) : IAttribute
 where TOwner : IEntity
 {
-    public bool IsScalar => false;
+    /// <inheritdoc />
     public Type Owner => typeof(TOwner);
+
+    /// <inheritdoc />
     public string Name => name;
+
+    /// <inheritdoc />
     public IAccumulator CreateAccumulator()
     {
         return new Accumulator();
     }
 
-    protected class Accumulator : IAccumulator
+    /// <inheritdoc />
+    private class Accumulator : IAccumulator
     {
         private HashSet<TType> _values = new();
         public void Add(object value)
@@ -50,5 +61,8 @@ public int ReadFrom(ref ReadOnlySpan<byte> reader, ISerializationRegistry regist
         }
     }
 
+    /// <summary>
+    /// The type of the items in the collection.
+    /// </summary>
     public Type Type => typeof(TType);
 }

src/NexusMods.EventSourcing.Abstractions/AttributeDefinitions/TypeAttributeDefinition.cs

@@ -9,7 +9,6 @@ namespace NexusMods.EventSourcing.Abstractions.AttributeDefinitions;
 /// <summary>
 /// An attribute for the type of an entity.
 /// </summary>
-/// <param name="attrName"></param>
 public class TypeAttributeDefinition : IAttribute<ScalarAccumulator<EntityDefinition>>
 {
     /// <inheritdoc />

src/NexusMods.EventSourcing.Abstractions/DependencyInjectionExtensions.cs

@@ -84,7 +84,7 @@ public static IServiceCollection AddEntity<T>(this IServiceCollection collection
         }
 
 
-        EntityStructureRegistry.Register(new EntityDefinition(type, entityAttribute.UUID, entityAttribute.Revision));
+        EntityStructureRegistry.Register(new EntityDefinition(type, entityAttribute.Uuid, entityAttribute.Revision));
         return collection;
     }
 

src/NexusMods.EventSourcing.Abstractions/EntityAttribute.cs

@@ -3,6 +3,9 @@
 
 namespace NexusMods.EventSourcing.Abstractions;
 
+/// <summary>
+/// Marks a class as an entity, and sets the UUID and revision of the entity.
+/// </summary>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
 public class EntityAttribute : Attribute
 {
@@ -11,13 +14,13 @@ public class EntityAttribute : Attribute
     /// the revision will cause the entity snapshots to be discarded, and regenerated
     /// during the next load.
     /// </summary>
-    /// <param name="uid"></param>
+    /// <param name="guid"></param>
     /// <param name="revision"></param>
     public EntityAttribute(string guid, ushort revision)
     {
         Span<byte> span = stackalloc byte[16];
         Guid.Parse(guid).TryWriteBytes(span);
-        UUID = BinaryPrimitives.ReadUInt128BigEndian(span);
+        Uuid = BinaryPrimitives.ReadUInt128BigEndian(span);
         Revision = revision;
     }
 
@@ -29,5 +32,5 @@ public EntityAttribute(string guid, ushort revision)
     /// <summary>
     /// The unique identifier of the entity *Type*.
     /// </summary>
-    public UInt128 UUID { get; }
+    public UInt128 Uuid { get; }
 }

src/NexusMods.EventSourcing.Abstractions/EntityAttributeDefinition.cs

@@ -4,7 +4,7 @@ namespace NexusMods.EventSourcing.Abstractions;
 
 /// <summary>
 /// A attribute that contains a lazy reference to another entity. The link can be updated via setting the entity Id, and
-/// retrieved via the <see cref="Get{TContext}"/> method. Think of this attribute like a foreign key in a database.
+/// retrieved via the <see cref="Get"/> method. Think of this attribute like a foreign key in a database.
 /// </summary>
 /// <param name="attrName"></param>
 /// <typeparam name="TOwner"></typeparam>
@@ -51,9 +51,7 @@ public void Unlink<TContext>(TContext context, EntityId<TOwner> owner)
     /// <summary>
     /// Gets the value of the attribute for the given entity.
     /// </summary>
-    /// <param name="context"></param>
     /// <param name="owner"></param>
-    /// <typeparam name="TContext"></typeparam>
     /// <returns></returns>
     public TOther Get(TOwner owner)
     {
@@ -63,7 +61,10 @@ public TOther Get(TOwner owner)
         throw new InvalidOperationException($"Attribute not found for {Name} on {Owner.Name} with id {owner.Id}");
     }
 
+    /// <inheritdoc />
     public Type Owner => typeof(TOwner);
+
+    /// <inheritdoc />
     public string Name => attrName;
     IAccumulator IAttribute.CreateAccumulator()
     {

src/NexusMods.EventSourcing.Abstractions/EntityCollectionAttributeDefinition.cs

@@ -1,5 +1,6 @@
 namespace NexusMods.EventSourcing.Abstractions;
 
+/// <inheritdoc />
 public class EntityCollectionAttributeDefinition<TOwner, TEntity>(string name) : ACollectionAttribute<TOwner, TEntity>(name) where TOwner : IEntity
     where TEntity : IEntity
 {

src/NexusMods.EventSourcing.Abstractions/EntityId.cs

@@ -5,11 +5,23 @@
 
 namespace NexusMods.EventSourcing.Abstractions;
 
+/// <summary>
+/// A unique identifier for an <see cref="IEntity"/>.
+/// </summary>
 [ValueObject<UInt128>]
 public readonly partial struct EntityId
 {
+    /// <summary>
+    /// Casts this <see cref="EntityId"/> to a <see cref="EntityId{T}"/> of the specified type.
+    /// </summary>
+    /// <typeparam name="T"></typeparam>
+    /// <returns></returns>
     public EntityId<T> Cast<T>() where T : IEntity => new(this);
 
+    /// <summary>
+    /// Creates a random <see cref="EntityId"/>.
+    /// </summary>
+    /// <returns></returns>
     public static EntityId NewId()
     {
         var guid = Guid.NewGuid();
@@ -19,8 +31,17 @@ public static EntityId NewId()
         return From(value);
     }
 
+    /// <summary>
+    /// Reads the <see cref="EntityId"/> from the specified <paramref name="data"/>.
+    /// </summary>
+    /// <param name="data"></param>
+    /// <returns></returns>
     public static EntityId From(ReadOnlySpan<byte> data) => new(BinaryPrimitives.ReadUInt128BigEndian(data));
 
+    /// <summary>
+    /// Writes the <see cref="EntityId"/> to the specified <paramref name="span"/>.
+    /// </summary>
+    /// <param name="span"></param>
     public void TryWriteBytes(Span<byte> span)
     {
         BinaryPrimitives.WriteUInt128BigEndian(span, Value);
@@ -95,7 +116,7 @@ public override string ToString()
     /// <summary>
     /// Converts the <see cref="EntityId{T}"/> to a <see cref="EntityId{T}"/> of another type.
     /// </summary>
-    /// <typeparam name="T"></typeparam>
+    /// <typeparam name="TTo"></typeparam>
     /// <returns></returns>
-    public EntityId<T> Cast<T>() where T : IEntity => new(Value);
+    public EntityId<TTo> Cast<TTo>() where TTo : IEntity => new(Value);
 }

src/NexusMods.EventSourcing.Abstractions/EntityIdDefinition.cs

@@ -6,6 +6,9 @@
 
 namespace NexusMods.EventSourcing.Abstractions;
 
+/// <summary>
+/// A internal class used for creating secondary indexes on entity Ids,
+/// </summary>
 public class EntityIdDefinition : IAttribute<EntityIdDefinitionAccumulator>, IIndexableAttribute<EntityId>
 {
     /// <inheritdoc />
@@ -31,6 +34,7 @@ public void WriteTo(Span<byte> span, EntityId value)
         BinaryPrimitives.WriteUInt128BigEndian(span, value.Value);
     }
 
+    /// <inheritdoc />
     public bool Equal(IAccumulator accumulator, EntityId val)
     {
         return ((EntityIdDefinitionAccumulator)accumulator).Id == val;
@@ -61,17 +65,25 @@ public void WriteTo(Span<byte> span, IAccumulator accumulator)
     }
 }
 
+/// <summary>
+/// Accumulator for the <see cref="EntityIdDefinition"/> attribute.
+/// </summary>
 public class EntityIdDefinitionAccumulator : IAccumulator
 {
+    /// <summary>
+    /// The Id of the entity.
+    /// </summary>
     public EntityId Id;
 
+    /// <inheritdoc />
     public void WriteTo(IBufferWriter<byte> writer, ISerializationRegistry registry)
     {
         var span = writer.GetSpan(16);
         BinaryPrimitives.WriteUInt128BigEndian(span, Id.Value);
         writer.Advance(16);
     }
 
+    /// <inheritdoc />
     public int ReadFrom(ref ReadOnlySpan<byte> data, ISerializationRegistry registry)
     {
         Id = EntityId.From(data);

src/NexusMods.EventSourcing.Abstractions/EntityStructureRegistry.cs

@@ -60,9 +60,6 @@ public static IEnumerable<IIndexableAttribute> AllIndexableAttributes()
     /// <summary>
     /// Registers an entity type in the global registry.
     /// </summary>
-    /// <param name="type"></param>
-    /// <param name="guid"></param>
-    /// <param name="revison"></param>
     public static void Register(EntityDefinition definition)
     {
         _entityDefinitionsByType.TryAdd(definition.Type, definition);
@@ -73,6 +70,7 @@ public static void Register(EntityDefinition definition)
     /// Returns all attributes for the given entity type.
     /// </summary>
     /// <param name="owner"></param>
+    /// <param name="result"></param>
     /// <returns></returns>
     public static bool TryGetAttributes(Type owner, [NotNullWhen(true)] out ConcurrentDictionary<string, IAttribute>? result)
     {

src/NexusMods.EventSourcing.Abstractions/IAttribute.cs

@@ -36,6 +36,6 @@ public interface IAttribute<TAccumulator> : IAttribute where TAccumulator : IAcc
     /// to lazily create accumulators.
     /// </summary>
     /// <returns></returns>
-    public TAccumulator CreateAccumulator();
+    public new TAccumulator CreateAccumulator();
 }
 

src/NexusMods.EventSourcing.Abstractions/IEntity.cs

@@ -21,7 +21,7 @@ public interface IEntity : INotifyPropertyChanged
 
 
     /// <summary>
-    /// The type descriptor for all entities. Emitted by the <see cref="IEventContext.New{TType}"/> method.
+    /// The type descriptor for all entities. Emitted by .New on the EntityContext
     /// </summary>
     public static readonly TypeAttributeDefinition TypeAttribute = new();
 

src/NexusMods.EventSourcing.Abstractions/IEntityContext.cs

@@ -46,7 +46,6 @@ public interface IEntityContext
     /// <param name="attributeDefinition"></param>
     /// <param name="accumulator"></param>
     /// <param name="createIfMissing"></param>
-    /// <typeparam name="TType"></typeparam>
     /// <typeparam name="TOwner"></typeparam>
     /// <typeparam name="TAttribute"></typeparam>
     /// <typeparam name="TAccumulator"></typeparam>

src/NexusMods.EventSourcing.Abstractions/IEventContext.cs

@@ -13,7 +13,6 @@ public interface IEventContext
     /// Gets the accumulator for the given attribute definition, if the accumulator does not exist it will be created. If
     /// the context is not setup for this entityId then false will be returned and the accumulator should be ignored.
     /// </summary>
-    /// <param name="entity"></param>
     /// <param name="entityId"></param>
     /// <param name="attributeDefinition"></param>
     /// <param name="accumulator"></param>

src/NexusMods.EventSourcing.Abstractions/IIndexableAttribute.cs

@@ -30,6 +30,7 @@ public interface IIndexableAttribute : IAttribute
     /// Writes the accumulator to the given span, which will be the size returned by <see cref="SpanSize"/>.
     /// </summary>
     /// <param name="span"></param>
+    /// <param name="accumulator"></param>
     public void WriteTo(Span<byte> span, IAccumulator accumulator);
 }
 
@@ -42,7 +43,7 @@ public interface IIndexableAttribute : IAttribute
 public interface IIndexableAttribute<TVal> : IIndexableAttribute
 {
     /// <summary>
-    /// Writes the accumulator to the given span, which will be the size returned by <see cref="SpanSize"/>.
+    /// Writes the accumulator to the given span, which will be the size returned by <see cref="IIndexableAttribute.SpanSize"/>.
     /// </summary>
     /// <param name="span"></param>
     /// <param name="value"></param>
@@ -54,7 +55,6 @@ public interface IIndexableAttribute<TVal> : IIndexableAttribute
     /// </summary>
     /// <param name="accumulator"></param>
     /// <param name="val"></param>
-    /// <typeparam name="TVal"></typeparam>
     /// <returns></returns>
     bool Equal(IAccumulator accumulator, TVal val);
 }

src/NexusMods.EventSourcing.Abstractions/ISingletonEntity.cs

@@ -5,5 +5,8 @@ namespace NexusMods.EventSourcing.Abstractions;
 /// </summary>
 public interface ISingletonEntity : IEntity
 {
+    /// <summary>
+    /// The singleton id of the entity.
+    /// </summary>
     public static virtual EntityId SingletonId { get; }
 }

src/NexusMods.EventSourcing.Abstractions/IndexedMultiEntityAttributeDefinition.cs

@@ -20,11 +20,20 @@ public class IndexedMultiEntityAttributeDefinition<TOwner, TKey, TOther>(string
     /// <inheritdoc />
     public string Name => name;
 
+    /// <inheritdoc />
     public IndexedMultiEntityAccumulator<TKey, TOther> CreateAccumulator()
     {
         return new IndexedMultiEntityAccumulator<TKey, TOther>();
     }
 
+    /// <summary>
+    /// Adds a new entity to the collection.
+    /// </summary>
+    /// <param name="context"></param>
+    /// <param name="owner"></param>
+    /// <param name="key"></param>
+    /// <param name="value"></param>
+    /// <typeparam name="TContext"></typeparam>
     public void Add<TContext>(TContext context, EntityId<TOwner> owner, TKey key, EntityId<TOther> value)
         where TContext : IEventContext
     {
@@ -61,13 +70,19 @@ public Dictionary<TKey, EntityId<TOther>> Get(TOwner entity)
     }
 }
 
+/// <summary>
+/// Accumulator for the <see cref="IndexedMultiEntityAttributeDefinition{TOwner,TKey,TOther}"/> attribute.
+/// </summary>
+/// <typeparam name="TKey"></typeparam>
+/// <typeparam name="TOther"></typeparam>
 public class IndexedMultiEntityAccumulator<TKey, TOther> : IAccumulator
     where TOther : AEntity<TOther>
     where TKey : notnull
 {
     internal Dictionary<TKey, EntityId<TOther>> _values = new();
     internal Dictionary<EntityId<TOther>, TKey> _keys = new();
 
+    /// <inheritdoc />
     public void WriteTo(IBufferWriter<byte> writer, ISerializationRegistry registry)
     {
         var getSpan = writer.GetSpan(2);
@@ -81,6 +96,7 @@ public void WriteTo(IBufferWriter<byte> writer, ISerializationRegistry registry)
         }
     }
 
+    /// <inheritdoc />
     public int ReadFrom(ref ReadOnlySpan<byte> input, ISerializationRegistry registry)
     {
         var originalSize = input.Length;

src/NexusMods.EventSourcing.Abstractions/MultiEntityAttributeDefinition.cs

@@ -25,8 +25,6 @@ public class MultiEntityAttributeDefinition<TOwner, TOther> : IAttribute<MultiEn
     /// database.
     /// </summary>
     /// <param name="name"></param>
-    /// <typeparam name="TOwner"></typeparam>
-    /// <typeparam name="TOther"></typeparam>
     public MultiEntityAttributeDefinition(string name)
     {
         _name = name;
@@ -58,7 +56,7 @@ public void Add<TContext>(TContext context, EntityId<TOwner> owner, EntityId<TOt
     /// </summary>
     /// <param name="context"></param>
     /// <param name="owner"></param>
-    /// <param name="value"></param>
+    /// <param name="values"></param>
     /// <typeparam name="TContext"></typeparam>
     public void AddAll<TContext>(TContext context, EntityId<TOwner> owner, EntityId<TOther>[] values)
         where TContext : IEventContext
@@ -129,6 +127,10 @@ public class MultiEntityAccumulator<TType> : IAccumulator
     /// </summary>
     public ReadOnlyObservableCollection<TType>? TransformedReadOnly = null;
 
+    /// <summary>
+    /// Initializes the accumulator
+    /// </summary>
+    /// <param name="context"></param>
     public void Init(IEntityContext context)
     {
         if (Transformed != null)

src/NexusMods.EventSourcing.Abstractions/ScalarAttribute.cs

@@ -59,9 +59,7 @@ public void Unset<TContext>(TContext context, EntityId<TOwner> owner)
      /// <summary>
      /// Gets the value of the attribute for the given entity.
      /// </summary>
-     /// <param name="context"></param>
      /// <param name="owner"></param>
-     /// <typeparam name="TContext"></typeparam>
      /// <returns></returns>
      public TType Get(TOwner owner)
      {