From be18745ec261c862728722e18873e347d044332a Mon Sep 17 00:00:00 2001
From: Kubat <maelle.martin@proton.me>
Date: Sat, 19 Apr 2025 14:12:30 +0200
Subject: [PATCH] Document the spell traits + make the cast/uncast methods taks
 a mut

---
 grimoire_engine_types/src/spell/mod.rs    |  2 ++
 grimoire_engine_types/src/spell/traits.rs | 13 +++++++++++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/grimoire_engine_types/src/spell/mod.rs b/grimoire_engine_types/src/spell/mod.rs
index 646ce42..35fd600 100644
--- a/grimoire_engine_types/src/spell/mod.rs
+++ b/grimoire_engine_types/src/spell/mod.rs
@@ -1,3 +1,5 @@
+//! The definition of Spells in the Grimoire engine.
+
 mod factory;
 mod arguments;
 mod traits;
diff --git a/grimoire_engine_types/src/spell/traits.rs b/grimoire_engine_types/src/spell/traits.rs
index 8c6c830..c180e62 100644
--- a/grimoire_engine_types/src/spell/traits.rs
+++ b/grimoire_engine_types/src/spell/traits.rs
@@ -1,27 +1,36 @@
 use crate::{error::SpellError, spell::SpellArguments, state::State};
 
+/// A spell, can be casted or reverted if we need to.
 pub trait Spell {
-    fn cast(&self, state: State) -> Result<State, SpellError>;
+    /// Cast the spell on a [State]. Returns a new [State].
+    fn cast(&mut self, state: State) -> Result<State, SpellError>;
 
-    fn uncast(&self, state: State) -> Result<State, SpellError>;
+    /// UnCast the spell from a [State]. Returns the previous [State].
+    fn uncast(&mut self, state: State) -> Result<State, SpellError>;
 }
 
+/// A [Spell] that we can create. Is used to be able to register it into a
+/// [crate::spell::SpellFactory].
 pub trait BuildableSpell
 where
     Self: Spell + TryFrom<SpellArguments, Error = SpellError> + 'static,
 {
+    /// The name of the spell.
     fn name() -> &'static str;
 
+    /// Aliases for this spell.
     fn aliases() -> &'static [&'static str] {
         &[]
     }
 
+    /// The list of names: the name and all the aliases.
     fn name_list() -> impl Iterator<Item = &'static str> {
         [Self::name()]
             .into_iter()
             .chain(Self::aliases().iter().copied())
     }
 
+    /// Create a spell from a set of arguments. May fail.
     fn create(arguments: SpellArguments) -> Result<Box<dyn Spell>, SpellError> {
         Self::try_from(arguments)
             .map(Box::new)
-- 
GitLab