From f44b36fad25ca63a40d5a6eefcae4d2288a18451 Mon Sep 17 00:00:00 2001
From: Steven Knipe <knipesteven@gmail.com>
Date: Fri, 17 Nov 2023 02:53:43 -0800
Subject: [PATCH] Improve documentation

---
 Mage/src/main/java/mage/abilities/Ability.java     | 10 +++++++---
 Mage/src/main/java/mage/abilities/AbilityImpl.java |  5 -----
 Mage/src/main/java/mage/util/CardUtil.java         |  4 ++--
 3 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/Mage/src/main/java/mage/abilities/Ability.java b/Mage/src/main/java/mage/abilities/Ability.java
index b2cf16b862b..4eb1d0e6f54 100644
--- a/Mage/src/main/java/mage/abilities/Ability.java
+++ b/Mage/src/main/java/mage/abilities/Ability.java
@@ -159,15 +159,19 @@ public interface Ability extends Controllable, Serializable {
     void addManaCostsToPay(ManaCost manaCost);
 
     /**
-     * Gets a map of the cost tags (set while casting/activating) of this ability, can be null if no tags have been set yet
-     * does NOT return the source permanent's tags
+     * Gets a map of the cost tags (set while casting/activating) of this ability, can be null if no tags have been set yet.
+     * Does NOT return the source permanent's tags.
+     * You should not be using this function in implementation of cards,
+     * this is a backing data structure used for internal storage.
+     * Use CardUtil {@link mage.util.CardUtil#getSourceCostsTag getSourceCostsTag} or {@link mage.util.CardUtil#checkSourceCostsTagExists checkSourceCostsTagExists} instead
      *
      * @return The map of tags and corresponding objects
      */
     Map<String, Object> getCostsTagMap();
 
     /**
-     * Set tag to the value, initializes this ability's tags map if it is null
+     * Set tag for this ability to the value, initializes this ability's tags map if needed.
+     * Should only be used from an {@link ActivatedAbility} (including {@link SpellAbility})
      */
     void setCostsTag(String tag, Object value);
 
diff --git a/Mage/src/main/java/mage/abilities/AbilityImpl.java b/Mage/src/main/java/mage/abilities/AbilityImpl.java
index 8cb62951227..57c049bcee8 100644
--- a/Mage/src/main/java/mage/abilities/AbilityImpl.java
+++ b/Mage/src/main/java/mage/abilities/AbilityImpl.java
@@ -706,11 +706,6 @@ public abstract class AbilityImpl implements Ability {
         return manaCostsToPay;
     }
 
-    /**
-     * Accessed to see what was optional/variable costs were paid
-     *
-     * @return
-     */
     @Override
     public Map<String, Object> getCostsTagMap() {
         return costsTagMap;
diff --git a/Mage/src/main/java/mage/util/CardUtil.java b/Mage/src/main/java/mage/util/CardUtil.java
index 9a2a21d1408..35952db3516 100644
--- a/Mage/src/main/java/mage/util/CardUtil.java
+++ b/Mage/src/main/java/mage/util/CardUtil.java
@@ -1680,13 +1680,13 @@ public final class CardUtil {
     /**
      * Returns the entire cost tags map of either the source ability, or the permanent source of the ability. May be null.
      * Works in any moment (even before source ability activated)
-     * Usually you should use one of the single tag functions instead
+     * Usually you should use one of the single tag functions instead: getSourceCostsTag() or checkSourceCostsTagExists()
+     * Use this function with caution, as it directly exposes the backing data structure.
      *
      * @param game
      * @param source
      * @return the tag map (or null)
      */
-    //
     public static Map<String, Object> getSourceCostsTagsMap(Game game, Ability source) {
         Map<String, Object> costTags;
         costTags = source.getCostsTagMap();