runelite-api: Fix various incorrect or misleading javadocs

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

@@ -47,7 +47,6 @@ public interface Client extends GameEngine
 {
 	/**
 	 * The client invokes these callbacks to communicate to
-	 * @return
 	 */
 	Callbacks getCallbacks();
 
@@ -58,7 +57,6 @@ public interface Client extends GameEngine
 	/**
 	 * Retrieve a global logger for the client.
 	 * This is most useful for mixins which can't have their own.
-	 * @return
 	 */
 	Logger getLogger();
 
@@ -351,7 +349,7 @@ public interface Client extends GameEngine
 	/**
 	 * Loads and creates the sprite images of the passed archive and file IDs.
 	 *
-	 * @param source the sprite database
+	 * @param source the sprite index
 	 * @param archiveId the sprites archive ID
 	 * @param fileId the sprites file ID
 	 * @return the sprite image of the file
@@ -359,16 +357,12 @@ public interface Client extends GameEngine
 	SpritePixels[] getSprites(IndexDataBase source, int archiveId, int fileId);
 
 	/**
-	 * Gets the sprite index database.
+	 * Gets the sprite index.
-	 *
-	 * @return the sprite database
 	 */
 	IndexDataBase getIndexSprites();
 
 	/**
-	 * Gets the script index database.
+	 * Gets the script index.
-	 *
-	 * @return the script database
 	 */
 	IndexDataBase getIndexScripts();
 
@@ -554,8 +548,7 @@ public interface Client extends GameEngine
 	 * Sets the array of open menu entries.
 	 * <p>
 	 * This method should typically be used in the context of the {@link net.runelite.api.events.MenuOpened}
-	 * event, since setting the menu entries will be overwritten the next
+	 * event, since setting the menu entries will be overwritten the next frame
-	 * time the menu entries are calculated.
 	 *
 	 * @param entries new array of open menu entries
 	 */
@@ -603,22 +596,15 @@ public interface Client extends GameEngine
 	 * plane, x and y the x-axis and y-axis coordinates of a tile
 	 * divided by the size of a chunk.
 	 * <p>
-	 * The bits of the int value held by the coordinates are structured
+	 * The bits of the int value held by the coordinates are -1 if there is no data,
-	 * with the following format:
+	 * structured in the following format:
-	 * <ul>
+	 * <pre>{@code
-	 *     <li>Bits 7 and 8 correspond to the plane</li>
+	 *  0                   1                   2                   3
-	 *     <li>Bits 9 to 18 correspond to the x-axis coordinate of the chunk</li>
+	 *  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-	 *     <li>Bits 19 to 29 correspond to the y-axis coordinate of the chunk</li>
+	 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-	 *     <li>Bits 30 and 31 correspond to the chunks rotation</li>
+	 * | |rot|     y chunk coord     |    x chunk coord    |pln|       |
-	 * </ul>
+	 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-	 * Note: The above positions assume that the left-most bit of an integer
+	 * }</pre>
-	 * is bit position 1, and the right-most bit 32.
-	 * ie.
-	 * 0000 0000 0000 0000 0000 0000 0000 0000
-	 *        PP XXXX XXXX XXYY YYYY YYYY YRR
-	 * Where P is the plane, X and Y the x/y axis coordinates, and R the chunks
-	 * rotation.
-	 *
 	 * @return the array of instance template chunks
 	 * @see Constants#CHUNK_SIZE
 	 * @see InstanceTemplates
@@ -1010,48 +996,32 @@ public interface Client extends GameEngine
 	ItemContainer getItemContainer(InventoryID inventory);
 
 	/**
-	 * Gets the index of the last integer added to the
+	 * Gets the length of the cs2 vm's int stack
-	 * {@link #getIntStack()} array.
-	 *
-	 * @return the array index
 	 */
 	int getIntStackSize();
 
 	/**
-	 * Sets the index of the last integer added to the
+	 * Sets the length of the cs2 vm's int stack
-	 * {@link #getIntStack()} array.
-	 *
-	 * @param stackSize the array index
 	 */
 	void setIntStackSize(int stackSize);
 
 	/**
-	 * Gets the integer stack
+	 * Gets the cs2 vm's int stack
-	 *
-	 * @return the array
 	 */
 	int[] getIntStack();
 
 	/**
-	 * Gets the index of the last string added to the
+	 * Gets the length of the cs2 vm's string stack
-	 * {@link #getStringStack()} array.
-	 *
-	 * @return the array index
 	 */
 	int getStringStackSize();
 
 	/**
-	 * Sets the index of the last string added to the
+	 * Sets the length of the cs2 vm's string stack
-	 * {@link #getStringStack()} array.
-	 *
-	 * @param stackSize the array index
 	 */
 	void setStringStackSize(int stackSize);
 
 	/**
-	 * Gets the string stack
+	 * Gets the cs2 vm's string stack
-	 *
-	 * @return the string stack
 	 */
 	String[] getStringStack();
 
@@ -1224,8 +1194,6 @@ public interface Client extends GameEngine
 
 	/**
 	 * Creates a new instance of a world.
-	 *
-	 * @return the created world
 	 */
 	World createWorld();
 
@@ -1238,7 +1206,9 @@ public interface Client extends GameEngine
 	SpritePixels drawInstanceMap(int z);
 
 	/**
-	 * Runs a RuneLite script.
+	 * Executes a client script from the cache
+	 *
+	 * This method must be ran on the client thread and is not reentrant
 	 *
 	 * @param id the script ID
 	 * @param args additional arguments to execute the script with
@@ -1521,8 +1491,6 @@ public interface Client extends GameEngine
 
 	/**
 	 * Gets the enabled state for the Oculus orb mode
-	 *
-	 * @return
 	 */
 	int getOculusOrbState();
 
@@ -1535,8 +1503,6 @@ public interface Client extends GameEngine
 
 	/**
 	 * Sets the normal moving speed when using oculus orb (default value is 12)
-	 *
-	 * @param speed speed
 	 */
 	void setOculusOrbNormalSpeed(int speed);
 

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

@@ -25,7 +25,7 @@
 package net.runelite.api;
 
 /**
- * Represents an indexed database, typically used for sprites.
+ * Represents an index in the cache
  */
 public interface IndexDataBase
 {

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

@@ -105,9 +105,7 @@ public interface ItemComposition
 	boolean isStackable();
 
 	/**
-	 * Returns whether or not the item can be traded to other players.
+	 * Returns whether or not the item can be sold on the grand exchange.
-	 *
-	 * @return true if tradeable, false otherwise
 	 */
 	boolean isTradeable();
 

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

@@ -28,7 +28,7 @@ import lombok.Data;
 import net.runelite.api.Script;
 
 /**
- * An event where a Runelite ASM script is called.
+ * A callback from a runelite_callback opcode in a cs2
  */
 @Data
 public class ScriptCallbackEvent

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

@@ -32,8 +32,8 @@ import net.runelite.api.Point;
 /**
  * Represents an on-screen UI element that is drawn on the canvas.
  * <p>
- * It should be noted that unique RuneLite elements are note widgets
+ * It should be noted that most RuneLite-added elements are not Widgets, but are
- * themselves, and that Widgets are primarily RuneScape elements.
+ * an Overlay. Notable exceptions include bank tag tabs and chatbox inputs
  * <p>
  * Examples of Widgets include:
  * <ul>
@@ -49,7 +49,6 @@ public interface Widget
 	/**
 	 * Gets the widgets ID.
 	 *
-	 * @return the widget ID
 	 * @see WidgetID
 	 */
 	int getId();
@@ -57,42 +56,38 @@ public interface Widget
 	/**
 	 * Gets the type of the widget.
 	 *
-	 * @return the widget type
+	 * @see WidgetType
 	 */
 	int getType();
 
 	/**
 	 * Sets the type of the widget.
 	 *
-	 * @param type the new widget type
+	 * @see WidgetType
 	 */
 	void setType(int type);
 
 	/**
 	 * Gets the type of content displayed by the widget.
-	 *
-	 * @return the content type
 	 */
 	int getContentType();
 
 	/**
 	 * Sets the type of content displayed by the widget.
-	 *
-	 * @param contentType the new content type
 	 */
 	void setContentType(int contentType);
 
 	/**
 	 * Gets the current click configuration of the widget.
 	 *
-	 * @return the click configuration
+	 * @see WidgetConfig
 	 */
 	int getClickMask();
 
 	/**
 	 * Sets the click configuration of the widget.
 	 *
-	 * @param mask the new configuration
+	 * @see WidgetConfig
 	 */
 	void setClickMask(int mask);
 
@@ -111,22 +106,19 @@ public interface Widget
 	int getParentId();
 
 	/**
-	 * Safely gets a child widget at a specific index from {@link #getChildren}.
+	 * Gets a dynamic child by index
 	 *
-	 * @param index the raw index into the array
+	 * @throws IndexOutOfBoundsException if the index is outside of the child array
-	 * @return child widget, or null if the index does not exist
 	 */
 	Widget getChild(int index);
 
 	/**
-	 * Gets all children of this widget.
+	 * Gets the dynamic children of this widget in a sparse array
-	 *
-	 * @return the widgets children
 	 */
 	Widget[] getChildren();
 
 	/**
-	 * Sets the widget children
+	 * Sets the dynamic children sparse array
 	 */
 	void setChildren(Widget[] children);
 
@@ -161,8 +153,11 @@ public interface Widget
 	/**
 	 * Sets the relative x-axis coordinate to the widgets parent.
 	 *
-	 * @param x the new relative coordinate
+	 * You do not want to use this. Use {@link #setOriginalX(int)}, {@link #setXPositionMode(int)}
+	 * and {@link #revalidate()}. Almost any interaction with this widget from a clientscript will
+	 * recalculate this value.
 	 */
+	@Deprecated
 	void setRelativeX(int x);
 
 	/**
@@ -175,8 +170,11 @@ public interface Widget
 	/**
 	 * Sets the relative y-axis coordinate to the widgets parent.
 	 *
-	 * @param y the new relative coordinate
+	 * You do not want to use this. Use {@link #setOriginalY(int)}, {@link #setYPositionMode(int)}
+	 * and {@link #revalidate()}. Almost any interaction with this widget from a clientscript will
+	 * recalculate this value.
 	 */
+	@Deprecated
 	void setRelativeY(int y);
 
 	/**
@@ -194,9 +192,9 @@ public interface Widget
 	void setText(String text);
 
 	/**
-	 * Gets the text color as an RGB value.
+	 * Gets the color as an RGB value.
 	 *
-	 * @return the text color
+	 * @return RGB24 color
 	 * @see java.awt.Color#getRGB()
 	 */
 	int getTextColor();
@@ -204,22 +202,27 @@ public interface Widget
 	/**
 	 * Sets the RGB color of the displayed text or rectangle.
 	 *
-	 * @param textColor the new text color
+	 * @param textColor RGB24 color
 	 * @see java.awt.Color#getRGB()
 	 */
 	void setTextColor(int textColor);
 
 	/**
-	 * Sets the opacity of the rectangle
+	 * Gets the transparency of the rectangle
+	 *
+	 * @return 0 = fully opaque, 255 = fully transparent
 	 */
 	int getOpacity();
-	/**
-	 * Gets the opacity of the rectangle
-	 */
-	void setOpacity(int opacity);
 
 	/**
-	 * Gets the name of the widget.
+	 * Sets the transparency of the rectangle
+	 *
+	 * @param transparency 0 = fully opaque, 255 = fully transparent
+	 */
+	void setOpacity(int transparency);
+
+	/**
+	 * Gets the name "op base" of the widget.
 	 * <p>
 	 * The name of the widget is used in the tooltip when an action is
 	 * available. For example, the widget that activates quick prayers
@@ -263,6 +266,8 @@ public interface Widget
 	/**
 	 * Checks whether this widget or any of its parents are hidden.
 	 *
+	 * This must be ran on the client thread
+	 *
 	 * @return true if this widget or any parent is hidden, false otherwise
 	 */
 	boolean isHidden();
@@ -276,7 +281,7 @@ public interface Widget
 	boolean isSelfHidden();
 
 	/**
-	 * Sets the hidden state of this widget.
+	 * Sets the self-hidden state of this widget.
 	 *
 	 * @param hidden new hidden state
 	 */
@@ -310,8 +315,11 @@ public interface Widget
 	/**
 	 * Sets the width of the widget.
 	 *
-	 * @param width the new width
+	 * You do not want to use this. Use {@link #setOriginalWidth(int)}, {@link #setWidthMode(int)}
+	 * and {@link #revalidate()}. Almost any interaction with this widget from a clientscript will
+	 * recalculate this value.
 	 */
+	@Deprecated
 	void setWidth(int width);
 
 	/**
@@ -324,8 +332,11 @@ public interface Widget
 	/**
 	 * Sets the height of the widget.
 	 *
-	 * @param height the new height
+	 * You do not want to use this. Use {@link #setOriginalHeight(int)}, {@link #setHeightMode(int)}
+	 * and {@link #revalidate()}. Almost any interaction with this widget from a clientscript will
+	 * recalculate this value.
 	 */
+	@Deprecated
 	void setHeight(int height);
 
 	/**
@@ -348,6 +359,7 @@ public interface Widget
 	 * @param index index of the item
 	 * @return the widget item at index, or null if an item at index
 	 * does not exist
+	 * @throws IndexOutOfBoundsException if the index is out of bounds
 	 */
 	WidgetItem getWidgetItem(int index);
 
@@ -380,8 +392,8 @@ public interface Widget
 	void setItemQuantity(int quantity);
 
 	/**
-	 * Checks whether or not the drawn area of this widget contains
+	 * Checks if the passed canvas points is inside of this widget's
-	 * a point on the canvas.
+	 * {@link #getBounds() bounds}
 	 *
 	 * @param point the canvas point
 	 * @return true if this widget contains the point, false otherwise
@@ -429,65 +441,63 @@ public interface Widget
 	void setScrollHeight(int height);
 
 	/**
-	 * Gets the original x-axis coordinate.
+	 * Gets the X coordinate of this widget before being adjusted by
-	 *
+	 * {@link #getXPositionMode()}}.
-	 * @return the original coordinate
 	 */
 	int getOriginalX();
 
 	/**
-	 * Sets the original x-axis coordinate.
+	 * Sets the X input to the {@link WidgetPositionMode}. {@link #revalidate()} must be
+	 * called for the new values to take effect.
 	 *
-	 * @param originalX the new coordinate
+	 * @see #setXPositionMode(int)
 	 */
 	void setOriginalX(int originalX);
 
 	/**
-	 * Gets the original y-axis coordinate.
+	 * Gets the Y coordinate of this widget before being adjusted by
-	 *
+	 * {@link #getYPositionMode()}}
-	 * @return the original coordinate
 	 */
 	int getOriginalY();
 
 	/**
-	 * Sets the original y-axis coordinate.
+	 * Sets the Y input to the {@link WidgetPositionMode}. {@link #revalidate()} must be
+	 * called for the new values to take effect.
 	 *
-	 * @param originalY the new coordinate
+	 * @see #setYPositionMode(int)
 	 */
 	void setOriginalY(int originalY);
 
 	/**
-	 * Gets the original height of the widget.
+	 * Gets the height coordinate of this widget before being adjusted by
-	 *
+	 * {@link #getHeightMode()}
-	 * @return the original height
 	 */
 	int getOriginalHeight();
 
 	/**
-	 * Sets the original height of the widget.
+	 * Sets the height input to the {@link WidgetSizeMode}. {@link #revalidate()} must be
+	 * called for the new values to take effect.
 	 *
-	 * @param originalHeight the original height
+	 * @see #setHeightMode(int)
 	 */
 	void setOriginalHeight(int originalHeight);
 
 	/**
-	 * Gets the original width of the widget.
+	 * Gets the width coordinate of this widget before being adjusted by
-	 *
+	 * {@link #getWidthMode()}
-	 * @return the original width
 	 */
 	int getOriginalWidth();
 
 	/**
-	 * Sets the original width of the widget.
+	 * Sets the width input to the {@link WidgetSizeMode}. {@link #revalidate()} must be
+	 * called for the new values to take effect.
 	 *
-	 * @param originalWidth the original width
+	 * @see #setWidthMode(int)
 	 */
 	void setOriginalWidth(int originalWidth);
 
 	/**
-	 * Gets the actions available on the widget.
+	 * Gets the menu options available on the widget as a sparse array.
-	 *
-	 * @return the actions
 	 */
 	String[] getActions();
 
@@ -505,10 +515,10 @@ public interface Widget
 	void deleteAllChildren();
 
 	/**
-	 * Creates a menu action on the widget
+	 * Creates a menu option on the widget
 	 *
 	 * @param index  The index of the menu
-	 * @param action The string to be displayed next to the widget's name in the context menu
+	 * @param action The verb to be displayed next to the widget's name in the context menu
 	 */
 	void setAction(int index, String action);
 
@@ -592,11 +602,15 @@ public interface Widget
 
 	/**
 	 * Returns the archive id of the font used
+	 *
+	 * @see net.runelite.api.FontID
 	 */
 	int getFontId();
 
 	/**
 	 * Sets the archive id of the font
+	 *
+	 * @see net.runelite.api.FontID
 	 */
 	void setFontId(int id);
 
@@ -661,7 +675,8 @@ public interface Widget
 	int getXPositionMode();
 
 	/**
-	 * Sets the mode that the X position is calculated from the original X position
+	 * Sets the mode that the X position is calculated from the original X position.
+	 * {@link #revalidate()} must be called for new values to take effect.
 	 *
 	 * @see WidgetPositionMode
 	 */
@@ -675,7 +690,8 @@ public interface Widget
 	int getYPositionMode();
 
 	/**
-	 * Sets the mode that the Y position is calculated from the original Y position
+	 * Sets the mode that the Y position is calculated from the original Y position.
+	 * {@link #revalidate()} must be called for new values to take effect.
 	 *
 	 * @see WidgetPositionMode
 	 */
@@ -717,7 +733,8 @@ public interface Widget
 	int getWidthMode();
 
 	/**
-	 * Sets the mode controlling widget width
+	 * Sets the mode controlling widget width.
+	 * {@link #revalidate()} must be called for new values to take effect.
 	 *
 	 * @see WidgetSizeMode
 	 */
@@ -731,7 +748,8 @@ public interface Widget
 	int getHeightMode();
 
 	/**
-	 * Sets the mode controlling widget width
+	 * Sets the mode controlling widget width.
+	 * {@link #revalidate()} must be called for new values to take effect.
 	 *
 	 * @see WidgetSizeMode
 	 */