Add doc to Definition.create() to explicitly state the "no side-effect" requirement

1 files changed, 9 insertions, 0 deletions

diff --git a/src/main/java/org/luxons/sevenwonders/game/data/definitions/Definition.java b/src/main/java/org/luxons/sevenwonders/game/data/definitions/Definition.java
index 15ecb255..6c6b4b19 100644
--- a/src/main/java/org/luxons/sevenwonders/game/data/definitions/Definition.java
+++ b/src/main/java/org/luxons/sevenwonders/game/data/definitions/Definition.java
@@ -11,5 +11,14 @@ import org.luxons.sevenwonders.game.Settings;
  */
 public interface Definition<T> {
 
+    /**
+     * Creates a T object from the given settings. This method mustn't mutate this Definition as it may be called
+     * multiple times with different settings.
+     *
+     * @param settings
+     *         the game settings to use to generate a game-specific object from this definition
+     *
+     * @return the new game-specific object created from this definition
+     */
     T create(Settings settings);
 }