Remove FluentResults, documentation

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;
 }