[libgdx] Javadoc.

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/Animation.java

@@ -46,7 +46,10 @@ import com.esotericsoftware.spine.attachments.Sequence;
 import com.esotericsoftware.spine.attachments.Sequence.SequenceMode;
 import com.esotericsoftware.spine.attachments.VertexAttachment;
 
-/** Stores a list of timelines to animate a skeleton's pose over time. */
+/** Stores a list of timelines to animate a skeleton's pose over time.
+ * <p>
+ * See <a href='https://esotericsoftware.com/spine-applying-animations#Timeline-API'>Applying Animations</a> in the Spine Runtimes
+ * Guide. */
 public class Animation {
 	final String name;
 	float duration;
@@ -116,7 +119,9 @@ public class Animation {
 
 	/** Applies the animation's timelines to the specified skeleton.
 	 * <p>
-	 * See {@link Timeline#apply(Skeleton, float, float, Array, float, boolean, boolean, boolean, boolean)}.
+	 * See {@link Timeline#apply(Skeleton, float, float, Array, float, boolean, boolean, boolean, boolean)} and
+	 * <a href='https://esotericsoftware.com/spine-applying-animations#Timeline-API'>Applying Animations</a> in the Spine Runtimes
+	 * Guide.
 	 * @param skeleton The skeleton the animation is applied to. This provides access to the bones, slots, and other skeleton
 	 *           components the timelines may change.
 	 * @param lastTime The last time in seconds this animation was applied. Some timelines trigger only at discrete times, in which
@@ -136,7 +141,7 @@ public class Animation {
 	 * @param add If true, for timelines that support it, their values are added to the setup or current values (depending on
 	 *           <code>fromSetup</code>).
 	 * @param out True when the animation is mixing out, else it is mixing in. Used by timelines that perform instant transitions.
-	 * @param appliedPose True to modify the {@link Posed#getAppliedPose()}, else the {@link Posed#getPose()} is modified. */
+	 * @param appliedPose True to modify {@link Posed#getAppliedPose()}, else {@link Posed#getPose()} is modified. */
 	public void apply (Skeleton skeleton, float lastTime, float time, boolean loop, @Null Array<Event> events, float alpha,
 		boolean fromSetup, boolean add, boolean out, boolean appliedPose) {
 		if (skeleton == null) throw new IllegalArgumentException("skeleton cannot be null.");
@@ -175,7 +180,10 @@ public class Animation {
 		sliderTime, sliderMix
 	}
 
-	/** The base class for all timelines. */
+	/** The base class for all timelines.
+	 * <p>
+	 * See <a href='https://esotericsoftware.com/spine-applying-animations#Timeline-API'>Applying Animations</a> in the Spine
+	 * Runtimes Guide. */
 	static abstract public class Timeline {
 		final String[] propertyIds;
 		final float[] frames;
@@ -224,6 +232,9 @@ public class Animation {
 		}
 
 		/** Applies this timeline to the skeleton.
+		 * <p>
+		 * See <a href='https://esotericsoftware.com/spine-applying-animations#Timeline-API'>Applying Animations</a> in the Spine
+		 * Runtimes Guide.
 		 * @param skeleton The skeleton the timeline is applied to. This provides access to the bones, slots, and other skeleton
 		 *           components the timelines may change.
 		 * @param lastTime The last time in seconds this timeline was applied. Some timelines trigger only at discrete times, in
@@ -243,7 +254,7 @@ public class Animation {
 		 *           <code>fromSetup</code>).
 		 * @param out True when the animation is mixing out, else it is mixing in. Used by timelines that perform instant
 		 *           transitions.
-		 * @param appliedPose True to modify the {@link Posed#getAppliedPose()}, else the {@link Posed#getPose()} is modified. */
+		 * @param appliedPose True to modify {@link Posed#getAppliedPose()}, else {@link Posed#getPose()} is modified. */
 		abstract public void apply (Skeleton skeleton, float lastTime, float time, @Null Array<Event> events, float alpha,
 			boolean fromSetup, boolean add, boolean out, boolean appliedPose);
 
@@ -1577,7 +1588,7 @@ public class Animation {
 			return slotIndex;
 		}
 
-		/** The attachment for which the {@link SlotPose#getSequenceIndex()} will be set.
+		/** The attachment for which {@link SlotPose#getSequenceIndex()} will be set.
 		 * <p>
 		 * See {@link VertexAttachment#getTimelineAttachment()}. */
 		public Attachment getAttachment () {

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/AnimationState.java

@@ -47,7 +47,8 @@ import com.esotericsoftware.spine.Animation.Timeline;
 /** Applies animations over time, queues animations for later playback, mixes (crossfading) between animations, and applies
  * multiple animations on top of each other (layering).
  * <p>
- * See <a href='https://esotericsoftware.com/spine-applying-animations/'>Applying Animations</a> in the Spine Runtimes Guide. */
+ * See <a href='https://esotericsoftware.com/spine-applying-animations#AnimationState-API'>Applying Animations</a> in the Spine
+ * Runtimes Guide. */
 public class AnimationState {
 	static final Animation emptyAnimation = new Animation("<empty>", new Array(true, 0, Timeline[]::new), 0);
 	static private final int SUBSEQUENT = 0, FIRST = 1, HOLD = 2, HOLD_FIRST = 3, SETUP = 1, CURRENT = 2;
@@ -575,11 +576,11 @@ public class AnimationState {
 	 * <p>
 	 * Mixing in is done by first setting an empty animation, then adding an animation using
 	 * {@link #addAnimation(int, Animation, boolean, float)} with the desired delay (an empty animation has a duration of 0) and on
-	 * the returned track entry, set the {@link TrackEntry#setMixDuration(float)}. Mixing from an empty animation causes the new
+	 * the returned track entry set {@link TrackEntry#setMixDuration(float)}. Mixing from an empty animation causes the new
 	 * animation to be applied more and more over the mix duration. Properties keyed in the new animation transition from the value
 	 * from lower tracks or from the setup pose value if no lower tracks key the property to the value keyed in the new animation.
 	 * <p>
-	 * See <a href='https://esotericsoftware.com/spine-applying-animations/#Empty-animations'>Empty animations</a> in the Spine
+	 * See <a href='https://esotericsoftware.com/spine-applying-animations#Empty-animations'>Empty animations</a> in the Spine
 	 * Runtimes Guide. */
 	public TrackEntry setEmptyAnimation (int trackIndex, float mixDuration) {
 		TrackEntry entry = setAnimation(trackIndex, emptyAnimation, false);
@@ -593,8 +594,8 @@ public class AnimationState {
 	 * {@link #setEmptyAnimation(int, float)}.
 	 * <p>
 	 * See {@link #setEmptyAnimation(int, float)} and
-	 * <a href='https://esotericsoftware.com/spine-applying-animations/#Empty-animations'>Empty animations</a> in the Spine
+	 * <a href='https://esotericsoftware.com/spine-applying-animations#Empty-animations'>Empty animations</a> in the Spine Runtimes
-	 * Runtimes Guide.
+	 * Guide.
 	 * @param delay If > 0, sets {@link TrackEntry#getDelay()}. If <= 0, the delay set is the duration of the previous track entry
 	 *           minus any mix duration plus the specified <code>delay</code> (ie the mix ends at (when <code>delay</code> = 0) or
 	 *           before (when <code>delay</code> < 0) the previous track entry duration). If the previous entry is looping, its
@@ -611,7 +612,7 @@ public class AnimationState {
 
 	/** Sets an empty animation for every track, discarding any queued animations, and mixes to it over the specified mix duration.
 	 * <p>
-	 * See <a href='https://esotericsoftware.com/spine-applying-animations/#Empty-animations'>Empty animations</a> in the Spine
+	 * See <a href='https://esotericsoftware.com/spine-applying-animations#Empty-animations'>Empty animations</a> in the Spine
 	 * Runtimes Guide. */
 	public void setEmptyAnimations (float mixDuration) {
 		boolean oldDrainDisabled = queue.drainDisabled;
@@ -667,7 +668,7 @@ public class AnimationState {
 		return entry;
 	}
 
-	/** Removes the {@link TrackEntry#getNext() next entry} and all entries after it for the specified entry. */
+	/** Removes {@link TrackEntry#getNext()} and all entries after it for the specified entry. */
 	public void clearNext (TrackEntry entry) {
 		TrackEntry next = entry.next;
 		while (next != null) {

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/Bone.java

@@ -32,13 +32,14 @@ package com.esotericsoftware.spine;
 import com.badlogic.gdx.utils.Array;
 import com.badlogic.gdx.utils.Null;
 
-/** A bone has a number of poses:
+/** A node in a skeleton's hierarchy with a transform that affects its children and their attachments. A bone has a number of
+ * poses:
  * <ul>
- * <li>{@link BoneData#getSetupPose()}: The setup pose.
+ * <li>{@link #getData()}: The setup pose.
- * <li>{@link #getPose()}: The local pose. Set by animations and app code.
+ * <li>{@link #getPose()}: The unconstrained local pose. Set by animations and application code.
- * <li>{@link #getAppliedPose()}: The applied local pose. This is the local pose modified by constraints and app code.
+ * <li>{@link #getAppliedPose()}: The constrained local pose. The {@link #getPose()} with modifications by constraints.
- * <li>The world transform on the applied pose, computed by {@link Skeleton#updateWorldTransform(Physics)} and
+ * <li>World transform (on the applied pose): the {@link #getAppliedPose()} combined with the parent world transform. Computed by
- * {@link BonePose#updateWorldTransform(Skeleton)}.
+ * {@link Skeleton#updateWorldTransform(Physics)} and {@link BonePose#updateWorldTransform(Skeleton)}.
  * </ul>
  */
 public class Bone extends PosedActive<BoneData, BoneLocal, BonePose> {

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/BoneLocal.java

@@ -66,6 +66,7 @@ public class BoneLocal implements Pose<BoneLocal> {
 		this.y = y;
 	}
 
+	/** Sets local x and y translation. */
 	public void setPosition (float x, float y) {
 		this.x = x;
 		this.y = y;
@@ -98,11 +99,13 @@ public class BoneLocal implements Pose<BoneLocal> {
 		this.scaleY = scaleY;
 	}
 
+	/** Sets local x and y scale. */
 	public void setScale (float scaleX, float scaleY) {
 		this.scaleX = scaleX;
 		this.scaleY = scaleY;
 	}
 
+	/** Sets local x and y scale to the same value. */
 	public void setScale (float scale) {
 		scaleX = scale;
 		scaleY = scale;

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/BonePose.java

@@ -253,7 +253,7 @@ public class BonePose extends BoneLocal implements Update {
 		}
 	}
 
-	/** Part of the world transform matrix for the X axis. */
+	/** The world transform <code>[a b][c d]</code> x-axis x component. */
 	public float getA () {
 		return a;
 	}
@@ -262,7 +262,7 @@ public class BonePose extends BoneLocal implements Update {
 		this.a = a;
 	}
 
-	/** Part of the world transform matrix for the Y axis. */
+	/** The world transform <code>[a b][c d]</code> y-axis x component. */
 	public float getB () {
 		return b;
 	}
@@ -271,7 +271,7 @@ public class BonePose extends BoneLocal implements Update {
 		this.b = b;
 	}
 
-	/** Part of the world transform matrix for the X axis. */
+	/** The world transform <code>[a b][c d]</code> x-axis y component. */
 	public float getC () {
 		return c;
 	}
@@ -280,7 +280,7 @@ public class BonePose extends BoneLocal implements Update {
 		this.c = c;
 	}
 
-	/** Part of the world transform matrix for the Y axis. */
+	/** The world transform <code>[a b][c d]</code> y-axis y component. */
 	public float getD () {
 		return d;
 	}
@@ -307,7 +307,8 @@ public class BonePose extends BoneLocal implements Update {
 		this.worldY = worldY;
 	}
 
-	/** The world rotation for the X axis, calculated using {@link #a} and {@link #c}. */
+	/** The world rotation for the X axis, calculated using {@link #a} and {@link #c}. This is the direction the bone is
+	 * pointing. */
 	public float getWorldRotationX () {
 		return atan2Deg(c, a);
 	}

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/Pose.java

@@ -1,6 +1,8 @@
 
 package com.esotericsoftware.spine;
 
+/** An interface for an object representing a pose. */
 public interface Pose<P> {
+	/** Sets this pose to the specified pose. */
 	public void set (P pose);
 }

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/Posed.java

@@ -1,6 +1,13 @@
 
 package com.esotericsoftware.spine;
 
+/** The base class for an object with a number of poses:
+ * <ul>
+ * <li>{@link #getData()}: The setup pose.
+ * <li>{@link #getPose()}: The unconstrained pose. Set by animations and application code.
+ * <li>{@link #getAppliedPose()}: The constrained pose. The {@link #getPose()} with modifications by constraints.
+ * </ul>
+ */
 abstract public class Posed< //
 	D extends PosedData<P>, //
 	P extends Pose, //
@@ -19,31 +26,38 @@ abstract public class Posed< //
 		applied = pose;
 	}
 
+	/** Sets the unconstrained pose to the setup pose. */
 	public void setupPose () {
 		pose.set(data.setup);
 	}
 
-	/** The constraint's setup pose data. */
+	/** The setup pose data. May be shared with multiple instances. */
 	public D getData () {
 		return data;
 	}
 
+	/** The unconstrained pose for this object, set by animations and application code. */
 	public P getPose () {
 		return pose;
 	}
 
+	/** If no constraints modify this object, the applied pose is the same as the {@link #pose}. Otherwise it is a copy of the
+	 * {@link #pose} modified by constraints. */
 	public A getAppliedPose () {
 		return applied;
 	}
 
+	/** Sets the applied pose to the unconstrained pose, for when no constraints will modify the pose. */
 	void pose () { // Port: usePose
 		applied = pose;
 	}
 
+	/** Sets the applied pose to the constrained pose, in anticipation of the applied pose being modified by constraints. */
 	void constrained () { // Port: useConstrained
 		applied = constrained;
 	}
 
+	/** Sets the constrained pose to the unconstrained pose, as a starting point for constraints to be applied. */
 	void reset () { // Port: resetConstrained
 		constrained.set(pose);
 	}

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/PosedActive.java

@@ -1,6 +1,7 @@
 
 package com.esotericsoftware.spine;
 
+/** A posed object that may be active or inactive. */
 abstract public class PosedActive< //
 	D extends PosedData<P>, //
 	P extends Pose, //

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/PosedData.java

@@ -29,7 +29,7 @@
 
 package com.esotericsoftware.spine;
 
-/** The base class for all constrained datas. */
+/** The base class for storing setup data for a posed object. May be shared with multiple instances. */
 abstract public class PosedData<P extends Pose> {
 	final String name;
 	final P setup;

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/Skeleton.java

@@ -374,8 +374,8 @@ public class Skeleton {
 		setSkin(skin);
 	}
 
-	/** Sets the skin used to look up attachments before looking in the {@link SkeletonData#getDefaultSkin() default skin}. If the
+	/** Sets the skin used to look up attachments before looking in {@link SkeletonData#getDefaultSkin()}. If the skin is changed,
-	 * skin is changed, {@link #updateCache()} is called.
+	 * {@link #updateCache()} is called.
 	 * <p>
 	 * Attachments from the new skin are attached if the corresponding attachment from the old skin was attached. If there was no
 	 * old skin, each slot's setup mode attachment is attached from the new skin.

spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/attachments/VertexAttachment.java

@@ -73,7 +73,7 @@ abstract public class VertexAttachment extends Attachment {
 		worldVerticesLength = other.worldVerticesLength;
 	}
 
-	/** Transforms the attachment's local {@link #getVertices()} to world coordinates. If the {@link SlotPose#getDeform()} is not
+	/** Transforms the attachment's local {@link #getVertices()} to world coordinates. If {@link SlotPose#getDeform()} is not
 	 * empty, it is used to deform the vertices.
 	 * <p>
 	 * See <a href="https://esotericsoftware.com/spine-runtime-skeletons#World-transforms">World transforms</a> in the Spine
@@ -143,7 +143,7 @@ abstract public class VertexAttachment extends Attachment {
 	}
 
 	/** The bones that affect the {@link #getVertices()}. The entries are, for each vertex, the number of bones affecting the
-	 * vertex followed by that many bone indices, which is the {@link Skeleton#getBones()} index. Null if this attachment has no
+	 * vertex followed by that many bone indices, which is {@link Skeleton#getBones()} index. Null if this attachment has no
 	 * weights. */
 	public @Null int[] getBones () {
 		return bones;