Remove FluentResults, documentation

PkmnLib.Dynamic/Libraries/DynamicLibrary.cs

@@ -1,4 +1,3 @@
-using PkmnLib.Dynamic.ScriptHandling;
 using PkmnLib.Dynamic.ScriptHandling.Registry;
 using PkmnLib.Static.Libraries;
 

PkmnLib.Dynamic/Models/BattleResult.cs

@@ -1,5 +1,8 @@
 namespace PkmnLib.Dynamic.Models;
 
+/// <summary>
+/// The result of a battle.
+/// </summary>
 public record struct BattleResult
 {
     private BattleResult(bool conclusiveResult, byte? winningSide)
@@ -8,7 +11,14 @@ public record struct BattleResult
         WinningSide = winningSide;
     }
     
+    /// <summary>
+    /// An inconclusive battle result. This means no side has won.
+    /// </summary>
     public static BattleResult Inconclusive => new(false, null);
+    
+    /// <summary>
+    /// A conclusive battle result. This means one side has won.
+    /// </summary>
     public static BattleResult Conclusive(byte winningSide) => new(true, winningSide);
     
     /// <summary>

PkmnLib.Dynamic/Models/Choices/FleeChoice.cs

@@ -1,5 +1,8 @@
 namespace PkmnLib.Dynamic.Models.Choices;
 
+/// <summary>
+/// A choice to flee from a battle.
+/// </summary>
 public interface IFleeChoice : ITurnChoice
 {
     

PkmnLib.Dynamic/Models/Choices/ItemChoice.cs

@@ -1,5 +1,8 @@
 namespace PkmnLib.Dynamic.Models.Choices;
 
+/// <summary>
+/// A choice to use an item
+/// </summary>
 public interface IItemChoice : ITurnChoice
 {
     

PkmnLib.Dynamic/Models/Choices/PassChoice.cs

@@ -1,5 +1,8 @@
 namespace PkmnLib.Dynamic.Models.Choices;
 
+/// <summary>
+/// A choice to pass a turn.
+/// </summary>
 public interface IPassChoice : ITurnChoice
 {
     

PkmnLib.Dynamic/Models/Choices/SwitchChoice.cs

@@ -1,5 +1,8 @@
 namespace PkmnLib.Dynamic.Models.Choices;
 
+/// <summary>
+/// A choice to switch to a different Pokémon.
+/// </summary>
 public interface ISwitchChoice : ITurnChoice
 {
     

PkmnLib.Dynamic/Models/Choices/TurnChoice.cs

@@ -2,6 +2,9 @@ using PkmnLib.Dynamic.ScriptHandling;
 
 namespace PkmnLib.Dynamic.Models.Choices;
 
+/// <summary>
+/// A choice that is made at the beginning of a turn. This can be a switch, flee, item, or pass choice.
+/// </summary>
 public interface ITurnChoice : IScriptSource
 {
     /// <summary>
@@ -33,24 +36,49 @@ public interface ITurnChoice : IScriptSource
     public void Fail();
 }
 
+/// <summary>
+/// A basic implementation of a <see cref="ITurnChoice"/>.
+/// </summary>
 public abstract class TurnChoice : ScriptSource, ITurnChoice
 {
+    /// <inheritdoc cref="TurnChoice"/>
     protected TurnChoice(IPokemon user)
     {
         User = user;
     }
 
+    /// <summary>
+    /// The Pokemon for which the choice is made.
+    /// </summary>
     public IPokemon User { get; }
 
+    /// <summary>
+    /// The speed of the user at the beginning of the turn.
+    /// </summary>
+    /// <remarks>
+    /// As a developer you do not need to set this value. It is set at the beginning of a turn automatically.
+    /// </remarks>
     public uint Speed { get; set; }
 
+    /// <summary>
+    /// A random value that is set at the beginning of the turn. This is used for tie breaking of the turn order.
+    /// </summary>
+    /// <remarks>
+    /// As a developer you do not need to set this value. It is set at the beginning of a turn automatically.
+    /// </remarks>
     public uint RandomValue { get; set; }
 
+    /// <summary>
+    /// Whether the choice has failed. A failed choice will stop running, and execute special fail handling
+    /// during turn execution.
+    /// </summary>
     public bool HasFailed { get; private set; }
 
+    /// <summary>
+    /// Fail the choice. This will prevent it from executing and run a specific fail handling during execution.
+    /// </summary>
     public void Fail()
     {
         HasFailed = true;
     }
-}
-
+}

PkmnLib.Dynamic/Models/ExecutingMove.cs

@@ -4,6 +4,9 @@ using PkmnLib.Static.Moves;
 
 namespace PkmnLib.Dynamic.Models;
 
+/// <summary>
+/// Data for a single hit on a target.
+/// </summary>
 public interface IHitData
 {
     /// <summary>
@@ -40,11 +43,6 @@ public interface IHitData
     /// Fails the hit.
     /// </summary>
     void Fail();
-
-    bool Equals(HitData? other);
-    bool Equals(object? other);
-    int GetHashCode();
-    string ToString();
 }
 
 /// <inheritdoc />

PkmnLib.Dynamic/Models/LearnedMove.cs

@@ -81,6 +81,7 @@ public class LearnedMoveImpl : ILearnedMove
 {
     private byte _maxPpModification = 0;
     
+    /// <inheritdoc cref="LearnedMoveImpl" />
     public LearnedMoveImpl(IMoveData moveData, MoveLearnMethod learnMethod)
     {
         MoveData = moveData;
@@ -97,8 +98,15 @@ public class LearnedMoveImpl : ILearnedMove
     /// <inheritdoc />
     public MoveLearnMethod LearnMethod { get; }
     
+    /// <summary>
+    /// The available power points for this move.
+    /// </summary>
     public byte CurrentPp { get; private set; }
     
+    /// <summary>
+    /// Try to use the move. This subtracts the amount of PP from the current PP. If the amount requested is
+    /// higher than the current PP, this will return false, and the PP will not be reduced.
+    /// </summary>
     public bool TryUse(byte amount = 1)
     {
         if (CurrentPp < amount)
@@ -108,7 +116,13 @@ public class LearnedMoveImpl : ILearnedMove
         return true;
     }
 
+    /// <summary>
+    /// Restore the PP to the maximum amount of PP.
+    /// </summary>
     public void RestoreAllUses() => CurrentPp = MaxPp;
 
+    /// <summary>
+    /// Restore the PP by a certain amount. This will prevent the PP from going above the maximum PP.
+    /// </summary>
     public void RestoreUses(byte amount) => CurrentPp = (byte)Math.Min(CurrentPp + amount, MaxPp);
 }

PkmnLib.Dynamic/Models/Pokemon.cs

@@ -288,5 +288,8 @@ public interface IPokemon : IScriptSource
 /// </summary>
 public interface IPokemonBattleData
 {
+    /// <summary>
+    /// The optional battle the Pokemon is in.
+    /// </summary>
     IBattle? Battle { get; }
 }

PkmnLib.Dynamic/Models/PokemonParty.cs

@@ -2,6 +2,9 @@ using System.Collections;
 
 namespace PkmnLib.Dynamic.Models;
 
+/// <summary>
+/// A collection of Pokemon.
+/// </summary>
 public interface IPokemonParty : IReadOnlyList<IPokemon?>
 {
     /// <summary>
@@ -14,13 +17,21 @@ public interface IPokemonParty : IReadOnlyList<IPokemon?>
     /// </summary>
     void Swap(int index1, int index2);
 
+    /// <summary>
+    /// Whether the party has any Pokemon that could be used in battle.
+    /// </summary>
+    /// <remarks>
+    /// This will return false if all Pokemon are fainted, or eggs, etc.
+    /// </remarks>
     bool HasUsablePokemon();
 }
 
+/// <inheritdoc />
 public class PokemonParty : IPokemonParty
 {
     private readonly IPokemon?[] _pokemon;
 
+    /// <inheritdoc cref="PokemonParty" />
     public PokemonParty(int size)
     {
         _pokemon = new IPokemon[size];
@@ -43,7 +54,8 @@ public class PokemonParty : IPokemonParty
         (_pokemon[index1], _pokemon[index2]) = (_pokemon[index2], _pokemon[index1]);
 
 
-    public bool HasUsablePokemon() => _pokemon.Any(p => p != null && p.IsUsable);
+    /// <inheritdoc />
+    public bool HasUsablePokemon() => _pokemon.Any(p => p is { IsUsable: true });
     
     /// <inheritdoc />
     public IEnumerator<IPokemon?> GetEnumerator() => ((IEnumerable<IPokemon?>)_pokemon).GetEnumerator();

PkmnLib.Dynamic/ScriptHandling/Registry/ScriptAttribute.cs

@@ -1,15 +1,26 @@
 using JetBrains.Annotations;
 using PkmnLib.Static.Utils;
 
-namespace PkmnLib.Dynamic.ScriptHandling;
+namespace PkmnLib.Dynamic.ScriptHandling.Registry;
 
+/// <summary>
+/// Helper attribute to register scripts through reflection.    
+/// </summary>
 [AttributeUsage(AttributeTargets.Class)]
 [MeansImplicitUse]
 public class ScriptAttribute : Attribute
 {
+    /// <summary>
+    /// The category of the script it should be registered in.
+    /// </summary>
     public ScriptCategory Category { get; }
+
+    /// <summary>
+    /// The name of the script.
+    /// </summary>
     public StringKey Name { get; }
-    
+
+    /// <inheritdoc cref="ScriptAttribute"/>
     public ScriptAttribute(ScriptCategory category, string name)
     {
         Category = category;

PkmnLib.Dynamic/ScriptHandling/Registry/ScriptRegistry.cs

@@ -1,17 +1,26 @@
 using System.Linq.Expressions;
 using System.Reflection;
+using JetBrains.Annotations;
 using PkmnLib.Dynamic.Libraries;
 using PkmnLib.Static.Utils;
 
-namespace PkmnLib.Dynamic.ScriptHandling;
+namespace PkmnLib.Dynamic.ScriptHandling.Registry;
 
+/// <summary>
+/// A helper data class that's passed through all plugins when initializing a library, so they can
+/// register their scripts and other data.
+/// </summary>
 public class ScriptRegistry
 {
-    private Dictionary<(ScriptCategory category, StringKey name), Func<Script>> _scriptTypes = new();
+    private readonly Dictionary<(ScriptCategory category, StringKey name), Func<Script>> _scriptTypes = new();
     private IBattleStatCalculator? _battleStatCalculator;
     private IDamageCalculator? _damageCalculator;
     private IMiscLibrary? _miscLibrary;
 
+    /// <summary>
+    /// Automatically register all scripts in the given assembly that have the <see cref="ScriptAttribute"/>, and
+    /// inherit from <see cref="Script"/>.
+    /// </summary>
     public void RegisterAssemblyScripts(Assembly assembly)
     {
         var baseType = typeof(Script);
@@ -25,6 +34,10 @@ public class ScriptRegistry
         }
     }
 
+    /// <summary>
+    /// Register a script type with the given category and name.
+    /// </summary>
+    [PublicAPI]
     public void RegisterScriptType(ScriptCategory category, StringKey name, Type type)
     {
         if (type == null)
@@ -39,12 +52,21 @@ public class ScriptRegistry
         _scriptTypes[(category, name)] = Expression.Lambda<Func<Script>>(Expression.New(constructor)).Compile();
     }
 
+    /// <summary>
+    /// Register a battle stat calculator.
+    /// </summary>
     public void RegisterBattleStatCalculator<T>(T battleStatCalculator)
         where T : IBattleStatCalculator => _battleStatCalculator = battleStatCalculator;
 
+    /// <summary>
+    /// Register a damage calculator.
+    /// </summary>
     public void RegisterDamageCalculator<T>(T damageCalculator)
         where T : IDamageCalculator => _damageCalculator = damageCalculator;
 
+    /// <summary>
+    /// Register a misc library.
+    /// </summary>
     public void RegisterMiscLibrary<T>(T miscLibrary) where T : IMiscLibrary
         => _miscLibrary = miscLibrary;
 

PkmnLib.Dynamic/ScriptHandling/ScriptContainer.cs

@@ -3,25 +3,29 @@ using System.Diagnostics.CodeAnalysis;
 
 namespace PkmnLib.Dynamic.ScriptHandling;
 
+/// <summary>
+/// A holder class for a script. This is used so we can cache a list of these, and iterate over them, even when
+/// the underlying script changes.
+/// </summary>
 public class ScriptContainer : IEnumerable<ScriptContainer>
 {
-    private Script? _script = null;
-
+    /// <summary>
+    /// Whether this container is empty.
+    /// </summary>
     [MemberNotNullWhen(false, nameof(ScriptHandling.Script))]
-    public bool IsEmpty => _script is null;
-    
-    public Script? Script
-    {
-        get => _script;
-        set => _script = value;
-    }
+    public bool IsEmpty => Script is null;
+
+    /// <summary>
+    /// The script in this container.
+    /// </summary>
+    public Script? Script { get; set; } = null;
 
     /// <inheritdoc />
     public IEnumerator<ScriptContainer> GetEnumerator()
     {
         yield return this;
     }
-    
+
 
     IEnumerator IEnumerable.GetEnumerator()
     {

PkmnLib.Dynamic/ScriptHandling/ScriptExecution.cs

@@ -2,8 +2,14 @@ using System.Runtime.CompilerServices;
 
 namespace PkmnLib.Dynamic.ScriptHandling;
 
+/// <summary>
+/// Helper functions for script execution.
+/// </summary>
 public static class ScriptExecution
 {
+    /// <summary>
+    /// Executes a hook on all scripts in a source.
+    /// </summary>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static void RunScriptHook(this IScriptSource source, Action<Script> hook)
     {

PkmnLib.Dynamic/ScriptHandling/ScriptIterator.cs

@@ -2,10 +2,14 @@ using System.Collections;
 
 namespace PkmnLib.Dynamic.ScriptHandling;
 
+/// <summary>
+/// Iterator to figure out the scripts to run.
+/// </summary>
 public class ScriptIterator : IEnumerable<ScriptContainer>
 {
     private readonly IReadOnlyList<IEnumerable<ScriptContainer>> _scripts;
 
+    /// <inheritdoc cref="ScriptIterator"/>
     public ScriptIterator(IReadOnlyList<IEnumerable<ScriptContainer>> scripts)
     {
         _scripts = scripts;

PkmnLib.Dynamic/ScriptHandling/ScriptSet.cs

@@ -1,16 +1,58 @@
-using FluentResults;
+using PkmnLib.Static.Utils;
 
 namespace PkmnLib.Dynamic.ScriptHandling;
 
+/// <summary>
+/// A script set is a collection of scripts that can be accessed by a key.
+/// We can add, remove, and clear scripts from the set.
+/// This is generally used for volatile scripts.
+/// </summary>
 public interface IScriptSet : IEnumerable<ScriptContainer>
 {
-    Result<ScriptContainer> Add(Script script);
-    Result<ScriptContainer?> Add(string scriptKey);
-    ScriptContainer? Get(string scriptKey);
-    void Remove(string scriptKey);
+    /// <summary>
+    /// Adds a script to the set. If the script with that name already exists in this set, this
+    /// makes that script stack instead. The return value here is that script.
+    /// </summary>
+    ScriptContainer Add(Script script);
+
+    /// <summary>
+    /// Adds a script with a name to the set. If the script with that name already exists in this
+    /// set, this makes that script stack instead. The return value here is that script.
+    /// </summary>
+    ScriptContainer? Add(StringKey scriptKey);
+
+    /// <summary>
+    /// Gets a script from the set using its unique name.
+    /// </summary>
+    ScriptContainer? Get(StringKey scriptKey);
+
+    /// <summary>
+    /// Removes a script from the set using its unique name.
+    /// </summary>
+    void Remove(StringKey scriptKey);
+
+    /// <summary>
+    /// Clears all scripts from the set.
+    /// </summary>
     void Clear();
-    void Contains(string scriptKey);
+
+    /// <summary>
+    /// Checks if the set has a script with the given name.
+    /// </summary>
+    void Contains(StringKey scriptKey);
+
+    /// <summary>
+    /// Gets a script from the set at a specific index.
+    /// </summary>
     ScriptContainer At(int index);
+
+    /// <summary>
+    /// Gets the number of scripts in the set.
+    /// </summary>
     int Count { get; }
-    IEnumerable<string> GetScriptNames();
+
+    /// <summary>
+    /// Gets the names of all scripts in the set.
+    /// </summary>
+    IEnumerable<StringKey> GetScriptNames();
 }

PkmnLib.Dynamic/ScriptHandling/ScriptSource.cs

@@ -1,7 +1,13 @@
 namespace PkmnLib.Dynamic.ScriptHandling;
 
+/// <summary>
+/// A script source is an object that can hold scripts, and from which scripts can be executed.
+/// </summary>
 public interface IScriptSource
 {
+    /// <summary>
+    /// Gets an iterator over all scripts that are relevant for this source.
+    /// </summary>
     ScriptIterator GetScripts();
     
     /// <summary>
@@ -25,6 +31,7 @@ public interface IScriptSource
     void CollectScripts(List<IEnumerable<ScriptContainer>> scripts);
 }
 
+/// <inheritdoc />
 public abstract class ScriptSource : IScriptSource
 {
     /// <inheritdoc />
@@ -47,6 +54,5 @@ public abstract class ScriptSource : IScriptSource
     /// <inheritdoc />
     public abstract void CollectScripts(List<IEnumerable<ScriptContainer>> scripts);
 
-    /// <inheritdoc />
     private List<IEnumerable<ScriptContainer>>? _scripts;
 }

PkmnLib.Dynamic/StaticHelpers.cs

@@ -1,5 +1,8 @@
 namespace PkmnLib.Dynamic;
 
+/// <summary>
+/// A static helper class that contains functions that are used in multiple places.
+/// </summary>
 public static class StaticHelpers
 {
     /// <summary>