From 51e42a32315aac6bc7bfb6977503fb6a46977035 Mon Sep 17 00:00:00 2001
From: SoyChai <soychai@tuta.io>
Date: Sun, 25 Mar 2018 15:30:09 -0400
Subject: [PATCH] Expand tests for and document the Experience API

---
 .../java/net/runelite/api/Experience.java     | 29 +++++++++++++++++--
 .../java/net/runelite/api/ExperienceTest.java | 27 ++++++++++++-----
 2 files changed, 46 insertions(+), 10 deletions(-)

diff --git a/runelite-api/src/main/java/net/runelite/api/Experience.java b/runelite-api/src/main/java/net/runelite/api/Experience.java
index bcd83c0509..9fc393c678 100644
--- a/runelite-api/src/main/java/net/runelite/api/Experience.java
+++ b/runelite-api/src/main/java/net/runelite/api/Experience.java
@@ -30,10 +30,13 @@ import static java.lang.Math.max;
 public class Experience
 {
 	/**
-	 * Maximum level under 200m xp
+	 * Maximum virtual skill level at 200m xp
 	 */
 	public static final int MAX_VIRT_LEVEL = 126;
 
+	/**
+	 * Total xp requirements of each skill level
+	 */
 	private static final int[] XP_FOR_LEVEL = new int[MAX_VIRT_LEVEL];
 
 	static
@@ -49,6 +52,12 @@ public class Experience
 		}
 	}
 
+	/**
+	 * Gets the total quantity of xp required to hit a skill level.
+	 *
+	 * @param level Level between 1 and 126 (inclusive).
+	 * @return Positive quantity of xp.
+	 */
 	public static int getXpForLevel(int level)
 	{
 		if (level < 1 || level > MAX_VIRT_LEVEL)
@@ -60,11 +69,17 @@ public class Experience
 		return XP_FOR_LEVEL[level - 1];
 	}
 
+	/**
+	 * Gets the skill level reached with a total quantity of xp.
+	 *
+	 * @param xp Positive quantity of xp.
+	 * @return Level between 1 and 126 (inclusive).
+	 */
 	public static int getLevelForXp(int xp)
 	{
 		if (xp < 0)
 		{
-			throw new IllegalArgumentException("XP must not be negative");
+			throw new IllegalArgumentException("XP (" + xp + ") must not be negative");
 		}
 
 		int low = 0;
@@ -92,6 +107,11 @@ public class Experience
 		return high + 1;
 	}
 
+	/**
+	 * Calculates a high-precision combat level without integer rounding.
+	 *
+	 * @return Combat level between 1.15 and ~126.1 (assuming non-virtual levels).
+	 */
 	public static double getCombatLevelPrecise(int attackLevel, int strengthLevel,
 		int defenceLevel, int hitpointsLevel, int magicLevel,
 		int rangeLevel, int prayerLevel)
@@ -105,6 +125,11 @@ public class Experience
 		return base + max(melee, max(range, magic));
 	}
 
+	/**
+	 * Calculates a regular combat level.
+	 *
+	 * @return Combat level between 1 and 126 (assuming non-virtual levels).
+	 */
 	public static int getCombatLevel(int attackLevel, int strengthLevel,
 		int defenceLevel, int hitpointsLevel, int magicLevel,
 		int rangeLevel, int prayerLevel)
diff --git a/runelite-api/src/test/java/net/runelite/api/ExperienceTest.java b/runelite-api/src/test/java/net/runelite/api/ExperienceTest.java
index 55aec91784..c4e615bdbb 100644
--- a/runelite-api/src/test/java/net/runelite/api/ExperienceTest.java
+++ b/runelite-api/src/test/java/net/runelite/api/ExperienceTest.java
@@ -30,6 +30,7 @@ import org.junit.Test;
 public class ExperienceTest
 {
 	private static final int XP_FOR_99 = 13_034_431;
+	private static final int XP_FOR_126 = 188_884_740;
 
 	@Test
 	public void testGetXpForLevel()
@@ -37,6 +38,9 @@ public class ExperienceTest
 		int xp = Experience.getXpForLevel(99);
 		Assert.assertEquals(XP_FOR_99, xp);
 
+		xp = Experience.getXpForLevel(126);
+		Assert.assertEquals(XP_FOR_126, xp);
+
 		xp = Experience.getXpForLevel(1);
 		Assert.assertEquals(0, xp);
 	}
@@ -56,22 +60,29 @@ public class ExperienceTest
 	@Test
 	public void testGetLevelForXp()
 	{
-		int level;
-
-		level = Experience.getLevelForXp(XP_FOR_99);
-		Assert.assertEquals(99, level);
-
-		level = Experience.getLevelForXp(XP_FOR_99 + 1);
+		int level = Experience.getLevelForXp(XP_FOR_99);
 		Assert.assertEquals(99, level);
 
 		level = Experience.getLevelForXp(XP_FOR_99 - 1);
 		Assert.assertEquals(98, level);
 
+		level = Experience.getLevelForXp(XP_FOR_126);
+		Assert.assertEquals(126, level);
+
+		level = Experience.getLevelForXp(XP_FOR_126 - 1);
+		Assert.assertEquals(125, level);
+
+		level = Experience.getLevelForXp(Integer.MAX_VALUE);
+		Assert.assertEquals(126, level);
+
 		level = Experience.getLevelForXp(0);
 		Assert.assertEquals(1, level);
+	}
 
-		level = Experience.getLevelForXp(200_000_000);
-		Assert.assertEquals(126, level);
+	@Test(expected = IllegalArgumentException.class)
+	public void testGetLevelForNegativeXP()
+	{
+		Experience.getLevelForXp(-1);
 	}
 
 	@Test