Merge pull request #10036 from abextm/misc-docs

runelite-api: Add some more documentation

runelite-api/src/main/java/net/runelite/api/IndexedSprite.java

@@ -25,119 +25,39 @@
 package net.runelite.api;
 
 /**
- * Represents an indexed sprite.
+ * Represents an paletted sprite.
  */
 public interface IndexedSprite
 {
 	/**
-	 * Gets the pixels contained by the sprite.
-	 *
-	 * @return the sprite pixels
+	 * The bitmap of this sprite. Each value is an index into {@link #getPalette()}.
+	 * 0 is transparent
 	 */
 	byte[] getPixels();
-
-	/**
-	 * Sets the pixels contained by the sprite.
-	 *
-	 * @param pixels the new sprite pixels
-	 */
 	void setPixels(byte[] pixels);
 
 	/**
-	 * Gets the color palette for the sprites pixels.
-	 *
-	 * @return the color palette
+	 * The color palette in RGB. The zero index is unused.
 	 */
 	int[] getPalette();
-
-	/**
-	 * Sets the color palette for the sprites pixels.
-	 *
-	 * @param palette the new color palette
-	 */
 	void setPalette(int[] palette);
 
-	/**
-	 * Gets the offset of the sprite along the x-axis.
-	 *
-	 * @return the x-axis offset
-	 */
 	int getOffsetX();
-
-	/**
-	 * Sets the offset of the sprite along the x-axis.
-	 *
-	 * @param offsetX new x-axis offset
-	 */
 	void setOffsetX(int offsetX);
 
-	/**
-	 * Gets the offset of the sprite along the y-axis.
-	 *
-	 * @return the y-axis offset
-	 */
 	int getOffsetY();
-
-	/**
-	 * Sets the offset of the sprite along the y-axis.
-	 *
-	 * @param offsetY new y-axis offset
-	 */
 	void setOffsetY(int offsetY);
 
-	/**
-	 * Gets the width of the sprite.
-	 *
-	 * @return the width
-	 */
 	int getWidth();
-
-	/**
-	 * Sets the width of the sprite.
-	 *
-	 * @param width the new width
-	 */
 	void setWidth(int width);
 
-	/**
-	 * Gets the original width of the sprite.
-	 *
-	 * @return the width
-	 */
-	int getOriginalWidth();
 
-	/**
-	 * Sets the original width of the sprite.
-	 *
-	 * @param originalWidth the width
-	 */
+	int getHeight();
+	void setHeight(int height);
+	
+	int getOriginalWidth();
 	void setOriginalWidth(int originalWidth);
 
-	/**
-	 * Gets the height of the sprite.
-	 *
-	 * @return the height
-	 */
-	int getHeight();
-
-	/**
-	 * Sets the height of the sprite.
-	 *
-	 * @param height the height
-	 */
-	void setHeight(int height);
-
-	/**
-	 * Gets the original height of the sprite.
-	 *
-	 * @return the height
-	 */
 	int getOriginalHeight();
-
-	/**
-	 * Sets the original height of the sprite.
-	 *
-	 * @param originalHeight the height
-	 */
 	void setOriginalHeight(int originalHeight);
 }

runelite-api/src/main/java/net/runelite/api/NPCComposition.java

@@ -25,93 +25,69 @@
 package net.runelite.api;
 
 /**
- * Represents the template of a specific NPC type.
+ * Information about a specific {@link NpcID}
  */
 public interface NPCComposition
 {
 	/**
 	 * Gets the name of the NPC.
-	 *
-	 * @return the name
 	 */
 	String getName();
 
 	/**
 	 * Gets the model IDs that compose this NPC.
-	 *
-	 * @return the NPCs model IDs
 	 */
 	int[] getModels();
 
 	/**
-	 * Gets an array of possible right-click menu actions that can be
-	 * performed on the NPC.
-	 *
-	 * @return the menu actions
+	 * The 5 menuops this NPC has when in world. Index 0 corresponds to
+	 * {@link MenuAction#NPC_FIRST_OPTION}, Index 2 to
+	 * {@link MenuAction#NPC_SECOND_OPTION} and so on.
 	 */
 	String[] getActions();
 
-	/**
-	 * Gets whether the NPC can be clicked.
-	 *
-	 * @return true if the NPC can be clicked, false otherwise
-	 */
 	boolean isClickable();
 
 	/**
 	 * Gets whether the NPC is visible on the mini-map.
-	 *
-	 * @return the mini-map visible state
 	 */
 	boolean isMinimapVisible();
 
-	/**
-	 * Gets whether the NPC is visible.
-	 *
-	 * @return the visible state
-	 */
 	boolean isVisible();
 
 	/**
 	 * Gets the ID of the NPC.
 	 *
-	 * @return the ID of the NPC
 	 * @see NpcID
 	 */
 	int getId();
 
 	/**
-	 * Gets the combat level of the NPC.
-	 *
 	 * @return the combat level, -1 if none
 	 */
 	int getCombatLevel();
 
 	/**
-	 * Gets the configuration data for the NPC.
-	 *
-	 * @return the configuration data
+	 * Get the {@link NpcID}s of NPCs this can transform into, depending
+	 * on a {@link Varbits} or {@link VarPlayer}
 	 */
 	int[] getConfigs();
 
 	/**
-	 * Transforms this NPC into a new state, which may have a different ID.
+	 * Get the NPC composition the player's state says this NPC should
+	 * transmogrify into.
 	 *
-	 * @return the transformed composition
+	 * @throws NullPointerException if {@link #getConfigs()} is null
 	 */
 	NPCComposition transform();
 
 	/**
-	 * Gets the size of the NPC.
-	 *
-	 * @return the NPCs size
+	 * How many tiles wide this NPC is
 	 */
 	int getSize();
 
 	/**
 	 * Gets the displayed overhead icon of the NPC.
-	 *
-	 * @return the overhead icon
 	 */
 	HeadIcon getOverheadIcon();
 }

runelite-api/src/main/java/net/runelite/api/ObjectComposition.java

@@ -25,58 +25,52 @@
 package net.runelite.api;
 
 /**
- * Represents the template of a specific object.
+ * Information about a specific {@link ObjectID}
  */
 public interface ObjectComposition
 {
 	/**
 	 * Gets ID for the object.
 	 *
-	 * @return the object ID
+	 * @see ObjectID
 	 */
 	int getId();
 
 	/**
 	 * Gets the name of the object.
-	 *
-	 * @return the object name
 	 */
 	String getName();
 
 	/**
-	 * Gets an array of possible right-click menu actions that can be
-	 * performed on the object.
-	 *
-	 * @return the menu actions
+	 * The 5 menuops this object has when in world. Index 0 corresponds to
+	 * {@link MenuAction#GAME_OBJECT_FIRST_OPTION}, Index 2 to
+	 * {@link MenuAction#GAME_OBJECT_SECOND_OPTION} and so on.
 	 */
 	String[] getActions();
 
 	/**
-	 * Gets the map scene ID for the object.
-	 *
-	 * @return the scene ID
+	 * Gets the index of this object in the {@link Client#getMapScene()}
+	 * array, or -1 if it has no map scene icon
 	 */
 	int getMapSceneId();
 
 	/**
-	 * Gets the map icon ID for the object.
-	 *
-	 * @return the map icon ID
+	 * Gets the index of this object in the {@link Client#getMapIcons()}
+	 * array, or -1 if it has no full map icon
 	 */
 	int getMapIconId();
 
 	/**
-	 * Gets IDs for objects that are considered fakes of this object,
-	 * such as barrows walls.
-	 *
-	 * @return the impostor IDs
+	 * Get the {@link ObjectID}s of objects this can transform into, depending
+	 * on a {@link Varbits} or {@link VarPlayer}
 	 */
 	int[] getImpostorIds();
 
 	/**
-	 * Gets the impostor composition for this object.
+	 * Get the object composition the player's state says this object should
+	 * transmogrify into.
 	 *
-	 * @return the impostor
+	 * @throws NullPointerException if {@link #getImpostorIds()} is null
 	 */
 	ObjectComposition getImpostor();
 }

runelite-api/src/main/java/net/runelite/api/TextureProvider.java

@@ -30,21 +30,19 @@ public interface TextureProvider
 
 	/**
 	 * Set the brightness for textures, clearing the texture cache.
-	 * @param brightness
+	 *
+	 * .9 is the darkest value available in the standard options
+	 * .6 is the brightest value
 	 */
 	void setBrightness(double brightness);
 
 	/**
 	 * Get all textures
-	 *
-	 * @return
 	 */
 	Texture[] getTextures();
 
 	/**
 	 * Get the pixels for a texture
-	 * @param textureId
-	 * @return
 	 */
 	int[] load(int textureId);
 }

runelite-api/src/main/java/net/runelite/api/TileItem.java

@@ -30,17 +30,10 @@ package net.runelite.api;
 public interface TileItem extends Renderable
 {
 	/**
-	 * Gets the items ID.
-	 *
 	 * @return the ID of the item
 	 * @see ItemID
 	 */
 	int getId();
 
-	/**
-	 * Gets the items quantity.
-	 *
-	 * @return the items quantity
-	 */
 	int getQuantity();
 }

runelite-api/src/main/java/net/runelite/api/TileObject.java

@@ -32,88 +32,65 @@ import net.runelite.api.coords.LocalPoint;
 import net.runelite.api.coords.WorldPoint;
 
 /**
- * Represents an object that a tile holds.
+ * Represents an object on a Tile
  */
 public interface TileObject
 {
-	/**
-	 * Gets the hashed value of this object.
-	 *
-	 * @return the object hash
-	 */
 	long getHash();
 
 	/**
 	 * Gets the x-axis coordinate of the object in local context.
 	 *
-	 * @return the x-axis coordinate
+	 * @see LocalPoint
 	 */
 	int getX();
 
 	/**
 	 * Gets the y-axis coordinate of the object in local context.
 	 *
-	 * @return the y-axis coordinate
+	 * @see LocalPoint
 	 */
 	int getY();
 
 	/**
 	 * Gets the plane of the tile that the object is on.
-	 *
-	 * @return the tile plane
 	 */
 	int getPlane();
 
 	/**
 	 * Gets the ID of the object.
 	 *
-	 * @return the object ID
+	 * @see ObjectID
+	 * @see NullObjectID
 	 */
 	int getId();
 
-	/**
-	 * Gets the location coordinate of the object in the world.
-	 *
-	 * @return the world location
-	 */
 	WorldPoint getWorldLocation();
 
-	/**
-	 * Gets the local location of the object.
-	 *
-	 * @return the local location
-	 */
 	LocalPoint getLocalLocation();
 
 	/**
-	 * Gets the upper-left canvas point where this object is drawn.
-	 *
-	 * @return the canvas location
+	 * Calculates the position of the center of this tile on the canvas
 	 */
 	Point getCanvasLocation();
 
 	/**
-	 * Gets the upper-left canvas point where this object is drawn,
-	 * offset by the passed value.
+	 * Calculates the position of the center of this tile on the canvas
 	 *
-	 * @param zOffset the z-axis offset
-	 * @return the canvas location
+	 * @param zOffset Vertical offset to apply before projection
 	 */
 	Point getCanvasLocation(int zOffset);
 
 	/**
-	 * Gets the polygon of the objects model as drawn on the canvas.
-	 *
-	 * @return the canvas polygon
+	 * Creates a polygon outlining the tile this object is on
 	 */
 	Polygon getCanvasTilePoly();
 
 	/**
-	 * Gets the text position on the canvas.
+	 * Calculates the canvas point to center {@code text} above the tile this object is on.
 	 *
-	 * @param graphics the client graphics
-	 * @param text the text to draw
-	 * @param zOffset the offset from ground plane
+	 * @param graphics the graphics to use for font size calculation
+	 * @param zOffset Vertical offset to apply before projection
 	 * @return the canvas point to draw the text at
 	 */
 	Point getCanvasTextLocation(Graphics2D graphics, String text, int zOffset);
@@ -127,9 +104,7 @@ public interface TileObject
 	Point getMinimapLocation();
 
 	/**
-	 * Get the on-screen clickable area of the object.
-	 *
-	 * @return the clickable area
+	 * Calculate the on-screen clickable area of the object.
 	 */
 	@Nullable
 	Shape getClickbox();

runelite-api/src/main/java/net/runelite/api/VarClientInt.java

@@ -28,7 +28,11 @@ import lombok.AllArgsConstructor;
 import lombok.Getter;
 
 /**
- * An enumeration of integer local variables.
+ * Client side only, content-developer integers
+ *
+ * VarCInts are stored entirely in memory, or locally on a user's
+ * machine in the preferences2.dat file depending on how Jagex
+ * configured the variable
  */
 @AllArgsConstructor
 @Getter

runelite-api/src/main/java/net/runelite/api/VarClientStr.java

@@ -28,7 +28,11 @@ import lombok.AllArgsConstructor;
 import lombok.Getter;
 
 /**
- * An enumeration of string local variables.
+ * Client side only, content-developer strings
+ *
+ * VarCInts are stored entirely in memory, or locally on a user's
+ * machine in the preferences2.dat file depending on how Jagex
+ * configured the variable
  */
 @AllArgsConstructor
 @Getter

runelite-api/src/main/java/net/runelite/api/VarPlayer.java

@@ -28,7 +28,12 @@ import lombok.AllArgsConstructor;
 import lombok.Getter;
 
 /**
- * An enumeration of local player variables.
+ * Server controlled "content-developer" integers.
+ *
+ * VarPlayers are stored per RuneScape player save, and synchronized
+ * from the server to the client. The client can change them preemptively
+ * if it thinks they will change the next tick as a lag-hiding measure.
+ * The client CANNOT directly make the server change a varbit.
  */
 @AllArgsConstructor
 @Getter

runelite-api/src/main/java/net/runelite/api/Varbits.java

@@ -28,7 +28,15 @@ import lombok.AllArgsConstructor;
 import lombok.Getter;
 
 /**
- * An enumeration of local client variables.
+ * Server controlled "content-developer" integers.
+ *
+ * @see VarPlayer
+ *
+ * These differ from a {@link VarPlayer} in that VarBits can be
+ * less than 32 bits. One or more VarBits can be assigned to a
+ * backing VarPlayer, each with a static range of bits that it is
+ * allowed to access. This allows a more compact representation
+ * of small values, like booleans
  */
 @AllArgsConstructor
 @Getter

runelite-api/src/main/java/net/runelite/api/events/ScriptCallbackEvent.java

@@ -34,11 +34,12 @@ import net.runelite.api.Script;
 public class ScriptCallbackEvent
 {
 	/**
-	 * The script being called.
+	 * The script that is currently being executed
 	 */
 	private Script script;
+
 	/**
-	 * The name of the event that triggered script execution.
+	 * The name passed to runelite_callback
 	 */
 	private String eventName;
 }

runelite-api/src/main/java/net/runelite/api/events/VarClientIntChanged.java

@@ -28,7 +28,7 @@ package net.runelite.api.events;
 import lombok.Value;
 
 /**
- * An event where a varbit integer has changed.
+ * @see net.runelite.api.VarClientInt
  */
 @Value
 public class VarClientIntChanged

runelite-api/src/main/java/net/runelite/api/events/VarClientStrChanged.java

@@ -28,7 +28,7 @@ package net.runelite.api.events;
 import lombok.Value;
 
 /**
- * An event where a varbit string has changed.
+ * @see net.runelite.api.VarClientStr
  */
 @Value
 public class VarClientStrChanged

runelite-api/src/main/java/net/runelite/api/events/VarbitChanged.java

@@ -30,6 +30,11 @@ import lombok.Data;
 
 /**
  * An event when a varbit or varplayer has changed.
+ *
+ * If the client preemptively changes a varp and the server agrees
+ * the next tick, VarbitChanged will only be posted when the client
+ * changes the value, not the server. This can cause unintended effects
+ * if the VarPlayer has special engine behavior assigned to it.
  */
 @Data
 public class VarbitChanged

runelite-api/src/main/java/net/runelite/api/events/WidgetMenuOptionClicked.java

@@ -28,7 +28,7 @@ import lombok.Data;
 import net.runelite.api.widgets.WidgetInfo;
 
 /**
- * An event where an option has been clicked in a {@link net.runelite.api.widgets.Widget}s menu.
+ * A MenuManager widget menu was clicked. This event is NOT fired for non-MenuManager menu options
  */
 @Data
 public class WidgetMenuOptionClicked

runelite-api/src/main/java/net/runelite/api/widgets/JavaScriptCallback.java

@@ -26,6 +26,10 @@ package net.runelite.api.widgets;
 
 import net.runelite.api.ScriptEvent;
 
+/**
+ * An object that can be set as the first argument to a {@link Widget} listener
+ * to handle ScriptEvents with Java code, rather than cs2.
+ */
 @FunctionalInterface
 public interface JavaScriptCallback
 {