[flutter] More doc comments for core API.

spine-flutter/lib/spine_flutter.dart

@@ -3311,19 +3311,19 @@ class TrackEntry {
     _bindings.spine_track_entry_set_mix_time(_entry, mixTime);
   }
 
-  /// Seconds for mixing from the previous animation to this animation. Defaults to the value provided by AnimationStateData
+  /// Seconds for mixing from the previous animation to this animation. Defaults to the value provided by
-  /// {@link AnimationStateData#getMix(Animation, Animation)} based on the animation before this animation (if any).
+  /// [AnimationStateData.getMix] based on the animation before this animation (if any).
-  /// <p>
+  ///
   /// A mix duration of 0 still mixes out over one frame to provide the track entry being mixed out a chance to revert the
   /// properties it was animating. A mix duration of 0 can be set at any time to end the mix on the next
-  /// {@link AnimationState#update(float) update}.
+  /// [AnimationState.update].
-  /// <p>
+  ///
   /// The <code>mixDuration</code> can be set manually rather than use the value from
-  /// {@link AnimationStateData#getMix(Animation, Animation)}. In that case, the <code>mixDuration</code> can be set for a new
+  /// [AnimationStateData.getMix]. In that case, the <code>mixDuration</code> can be set for a new
-  /// track entry only before {@link AnimationState#update(float)} is first called.
+  /// track entry only before [AnimationState.update] is first called.
   /// <p>
-  /// When using {@link AnimationState#addAnimation(int, Animation, boolean, float)} with a <code>delay</code> <= 0, the
+  /// When using [AnimationState.addAnimation] with a <code>delay</code> <= 0, the
-  /// {@link #getDelay()} is set using the mix duration from the {@link AnimationStateData}. If <code>mixDuration</code> is set
+  /// [getDelay] is set using the mix duration from the [AnimationStateData]. If <code>mixDuration</code> is set
   /// afterward, the delay may need to be adjusted. For example:
   /// <code>entry.delay = entry.previous.getTrackComplete() - entry.mixDuration;</code>
   double getMixDuration() {
@@ -3334,6 +3334,12 @@ class TrackEntry {
     _bindings.spine_track_entry_set_mix_duration(_entry, mixDuration);
   }
 
+  /// Controls how properties keyed in the animation are mixed with lower tracks. Defaults to [MixBlend.replace].
+  ///
+  /// Track entries on track 0 ignore this setting and always use {@link MixBlend#first}.
+  ///
+  /// The <code>mixBlend</code> can be set for a new track entry only before [AnimationState.apply] is first
+  /// called.
   MixBlend getMixBlend() {
     return MixBlend.values[_bindings.spine_track_entry_get_mix_blend(_entry)];
   }
@@ -3342,16 +3348,16 @@ class TrackEntry {
     _bindings.spine_track_entry_set_mix_blend(_entry, mixBlend.value);
   }
 
-  /// The track entry for the previous animation when mixing from the previous animation to this animation, or NULL if no
+  /// The track entry for the previous animation when mixing from the previous animation to this animation, or null if no
-  /// mixing is currently occuring. When mixing from multiple animations, MixingFrom makes up a double linked list with MixingTo.
+  /// mixing is currently occurring. When mixing from multiple animations, <code>mixingFrom</code> makes up a linked list.
   TrackEntry? getMixingFrom() {
     final from = _bindings.spine_track_entry_get_mixing_from(_entry);
     if (from.address == nullptr.address) return null;
     return TrackEntry._(from, _state);
   }
 
-  /// The track entry for the next animation when mixing from this animation, or NULL if no mixing is currently occuring.
+  /// The track entry for the next animation when mixing from this animation to the next animation, or null if no mixing is
-  /// When mixing from multiple animations, MixingTo makes up a double linked list with MixingFrom.
+  /// currently occurring. When mixing to multiple animations, <code>mixingTo</code> makes up a linked list.
   TrackEntry? getMixingTo() {
     final to = _bindings.spine_track_entry_get_mixing_to(_entry);
     if (to.address == nullptr.address) return null;
@@ -3369,22 +3375,62 @@ class TrackEntry {
     _bindings.spine_track_entry_reset_rotation_directions(_entry);
   }
 
+  /// If this track entry is non-looping, the track time in seconds when [getAnimationEnd] is reached, or the current
+  /// [getTrackTime] if it has already been reached. If this track entry is looping, the track time when this
+  /// animation will reach its next [getAnimationEnd] (the next loop completion).
   double getTrackComplete() {
     return _bindings.spine_track_entry_get_track_complete(_entry);
   }
 
+  /// The listener for events generated by this track entry, or null.
+  ///
+  /// A track entry returned from [AnimationState.setAnimation] is already the current animation
+  /// for the track, so the track entry listener will not be called for [EventType.start].
   void setListener(AnimationStateListener? listener) {
     _state._setTrackEntryListener(_entry, listener);
   }
 }
 
-enum EventType { start, interrupt, end, complete, dispose, event }
+/// The event type passed to [AnimationStateListener]
+enum EventType {
+  /// Emitted when [TrackEntry] has been set as the current entry. [EventType.end] will occur when this entry will no
+  /// longer be applied.
+  start,
+  /// Emitted when another entry has replaced the current entry. This entry may continue being applied for
+  /// mixing.
+  interrupt,
+  /// Emitted when this entry will never be applied again. This only occurs if this entry has previously been set as the
+  /// current entry ([EventType.start] was emitted).
+  end,
+  /// Emitted every time the current entry's animation completes a loop. This may occur during mixing (after
+  /// [EventType.interrupted] is emitted).
+  ///
+  /// If [TrackEntry.getMixingTo] of the entry reported by the event is not null, the entry is mixing out (it is not the current entry).
+  ///
+  /// Because this event is triggered at the end of [AnimationState.apply], any animations set in response to
+  /// the event won't be applied until the next time the [AnimationState] is applied.
+  complete,
+  /// Emitted when this entry will be disposed. This may occur without the entry ever being set as the current entry.
+  ///
+  /// References to the entry should not be kept after <code>dispose</code> is called, as it may be destroyed or reused.
+  dispose,
+  /// Invoked when the current entry's animation triggers an event. This may occur during mixing (after
+  /// [EventType.interrupt] is emitted), see [TrackEntry.getEventThreshold].
+  ///
+  /// Because this event is triggered at the end of [AnimationState.apply], any animations set in response to
+  /// the event won't be applied until the next time the [AnimationState] is applied.
+  event
+}
 
+/// Stores the setup pose values for an [Event].
+///
+/// See <a href="http://esotericsoftware.com/spine-events">Events</a> in the Spine User Guide.
 class EventData {
   final spine_event_data _data;
 
   EventData._(this._data);
 
+  /// The name of the event, which is unique across all events in the skeleton.
   String getName() {
     final Pointer<Utf8> value = _bindings.spine_event_data_get_name(_data).cast();
     return value.toDartString();
@@ -3439,15 +3485,21 @@ class EventData {
   }
 }
 
+/// Stores the current pose values for an {@link Event}.
+///
+/// See [AnimationStateListener], [EventType.event], and
+/// <a href="http://esotericsoftware.com/spine-events">Events</a> in the Spine User Guide.
 class Event {
   final spine_event _event;
 
   Event._(this._event);
 
+  /// The events's setup pose data.
   EventData getData() {
     return EventData._(_bindings.spine_event_get_data(_event));
   }
 
+  /// The animation time this event was keyed.
   double getTime() {
     return _bindings.spine_event_get_time(_event);
   }
@@ -3496,13 +3548,22 @@ class Event {
   }
 }
 
+/// The callback to implement for receiving [TrackEntry] events. It is always safe to call [AnimationState] methods when receiving
+/// events.
+///
+/// TrackEntry events are collected during [AnimationState.update] and [AnimationState.apply] and
+/// fired only after those methods are finished.
+///
+/// See [TrackEntry.setListener] and [AnimationState.setListener].
 typedef AnimationStateListener = void Function(EventType type, TrackEntry entry, Event? event);
 
+/// Stores mix (crossfade) durations to be applied when {@link AnimationState} animations are changed.
 class AnimationStateData {
   final spine_animation_state_data _data;
 
   AnimationStateData._(this._data);
 
+  /// The SkeletonData to look up animations when they are specified by name.
   SkeletonData getSkeletonData() {
     return SkeletonData._(_bindings.spine_animation_state_data_get_skeleton_data(_data));
   }
@@ -3515,6 +3576,9 @@ class AnimationStateData {
     _bindings.spine_animation_state_data_set_default_mix(_data, defaultMix);
   }
 
+  /// Sets a mix duration by animation name.
+  ///
+  /// See [setMix].
   void setMixByName(String fromName, String toName, double duration) {
     final fromNative = fromName.toNativeUtf8(allocator: _allocator);
     final toNative = toName.toNativeUtf8(allocator: _allocator);
@@ -3523,6 +3587,8 @@ class AnimationStateData {
     _allocator.free(toNative);
   }
 
+  /// Returns the mix duration to use when changing from the specified animation to the other, or the [getDefaultMix] if
+  /// no mix duration has been set.
   double getMixByName(String fromName, String toName) {
     final fromNative = fromName.toNativeUtf8(allocator: _allocator);
     final toNative = toName.toNativeUtf8(allocator: _allocator);
@@ -3532,19 +3598,29 @@ class AnimationStateData {
     return duration;
   }
 
-  void setMix(Animation from, Animation to, double duration) {
+  /// Sets the mix duration when changing from the specified animation to the other.
+  ///
+  /// See [TrackEntry.mixDuration].
+  Future<void> setMix(Animation from, Animation to, double duration) async {
     _bindings.spine_animation_state_data_set_mix(_data, from._animation, to._animation, duration);
   }
 
+  /// Returns the mix duration to use when changing from the specified animation to the other, or the [getDefaultMix] if
+  /// no mix duration has been set.
   double getMix(Animation from, Animation to) {
     return _bindings.spine_animation_state_data_get_mix(_data, from._animation, to._animation);
   }
 
+  /// Removes all mix durations.
   void clear() {
     _bindings.spine_animation_state_data_clear(_data);
   }
 }
 
+/// Applies animations over time, queues animations for later playback, mixes (crossfading) between animations, and applies
+/// multiple animations on top of each other (layering).
+///
+/// See <a href='http://esotericsoftware.com/spine-applying-animations/'>Applying Animations</a> in the Spine Runtimes Guide.
 class AnimationState {
   final spine_animation_state _state;
   final spine_animation_state_events _events;
@@ -3561,8 +3637,7 @@ class AnimationState {
     }
   }
 
-  /// Increments the track entry times, setting queued animations as current if needed
+  /// Increments each track entry [TrackEntry.getTrackTime], setting queued animations as current if needed.
-  /// @param delta delta time
   void update(double delta) {
     _bindings.spine_animation_state_update(_state, delta);
 
@@ -3608,33 +3683,33 @@ class AnimationState {
     _bindings.spine_animation_state_events_reset(_events);
   }
 
-  /// Poses the skeleton using the track entry animations. There are no side effects other than invoking listeners, so the
+  /// Poses the skeleton using the track entry animations. The animation state is not changed, so can be applied to multiple
-  /// animation state can be applied to multiple skeletons to pose them identically.
+  /// skeletons to pose them identically.
+  ///
+  /// Returns true if any animations were applied.
   void apply(Skeleton skeleton) {
     _bindings.spine_animation_state_apply(_state, skeleton._skeleton);
   }
 
-  /// Removes all animations from all tracks, leaving skeletons in their previous pose.
+  /// Removes all animations from all tracks, leaving skeletons in their current pose.
-  /// It may be desired to use AnimationState.setEmptyAnimations(float) to mix the skeletons back to the setup pose,
+  ///
-  /// rather than leaving them in their previous pose.
+  /// It may be desired to use [setEmptyAnimations] to mix the skeletons back to the setup pose,
+  /// rather than leaving them in their current pose.
   void clearTracks() {
     _bindings.spine_animation_state_clear_tracks(_state);
   }
 
-  /// Removes all animations from the tracks, leaving skeletons in their previous pose.
+  /// Removes all animations from the track, leaving skeletons in their current pose.
-  /// It may be desired to use AnimationState.setEmptyAnimations(float) to mix the skeletons back to the setup pose,
+  ///
-  /// rather than leaving them in their previous pose.
+  /// It may be desired to use [setEmptyAnimations] to mix the skeletons back to the setup pose,
+  /// rather than leaving them in their current pose.
   void clearTrack(int trackIndex) {
     _bindings.spine_animation_state_clear_track(_state, trackIndex);
   }
 
-  /// Sets the current animation for a track, discarding any queued animations.
+  /// Sets an animation by name.
-  /// @param loop If true, the animation will repeat.
+  ///
-  /// If false, it will not, instead its last frame is applied if played beyond its duration.
+  /// See [setAnimation].
-  /// In either case TrackEntry.TrackEnd determines when the track is cleared.
-  /// @return
-  /// A track entry to allow further customization of animation playback. References to the track entry must not be kept
-  /// after AnimationState.Dispose.
   TrackEntry setAnimationByName(int trackIndex, String animationName, bool loop) {
     final animation = animationName.toNativeUtf8(allocator: _allocator);
     final entry = _bindings.spine_animation_state_set_animation_by_name(_state, trackIndex, animation.cast(), loop ? -1 : 0);
@@ -3643,20 +3718,23 @@ class AnimationState {
     return TrackEntry._(entry, this);
   }
 
+  /// Sets the current [animation] for a track at [trackIndex], discarding any queued animations. If the formerly current track entry was never
+  /// applied to a skeleton, it is replaced (not mixed from).
+  ///
+  /// If [loop] is true, the animation will repeat. If false it will not, instead its last frame is applied if played beyond its
+  /// duration. In either case [TrackEntry.getTrackEnd] determines when the track is cleared.
+  ///
+  /// Returns a track entry to allow further customization of animation playback. References to the track entry must not be kept
+  /// after the [EventType.dispose] event occurs.
   TrackEntry setAnimation(int trackIndex, Animation animation, bool loop) {
     final entry = _bindings.spine_animation_state_set_animation(_state, trackIndex, animation._animation, loop ? -1 : 0);
     if (entry.address == nullptr.address) throw Exception("Couldn't set animation ${animation.getName()}");
     return TrackEntry._(entry, this);
   }
 
-  /// Adds an animation to be played delay seconds after the current or last queued animation
+  /// Queues an animation by name.
-  /// for a track. If the track is empty, it is equivalent to calling setAnimation.
-  /// @param delay
-  /// Seconds to begin this animation after the start of the previous animation. May be &lt;= 0 to use the animation
-  /// duration of the previous track minus any mix duration plus the negative delay.
   ///
-  /// @return A track entry to allow further customization of animation playback. References to the track entry must not be kept
+  /// See [addAnimation].
-  /// after AnimationState.Dispose
   TrackEntry addAnimationByName(int trackIndex, String animationName, bool loop, double delay) {
     final animation = animationName.toNativeUtf8(allocator: _allocator);
     final entry = _bindings.spine_animation_state_add_animation_by_name(_state, trackIndex, animation.cast(), loop ? -1 : 0, delay);
@@ -3665,47 +3743,82 @@ class AnimationState {
     return TrackEntry._(entry, this);
   }
 
+  /// Adds an [animation] to be played after the current or last queued animation for a track at [trackIndex]. If the track is empty, it is
+  /// equivalent to calling [setAnimation].
+  ///
+  /// If [delay] > 0, sets [TrackEntry.getDelay]. If [delay] <= 0, the delay set is the duration of the previous track entry
+  /// minus any mix duration (from the [AnimationStateData]) plus the specified <code>delay</code> (ie the mix
+  /// ends at (<code>delay</code> = 0) or before (<code>delay</code> < 0) the previous track entry duration). If the
+  /// previous entry is looping, its next loop completion is used instead of its duration.
+  ///
+  /// Returns a track entry to allow further customization of animation playback. References to the track entry must not be kept
+  /// after the [EventType.dispose] event occurs.
   TrackEntry addAnimation(int trackIndex, Animation animation, bool loop, double delay) {
     final entry = _bindings.spine_animation_state_add_animation(_state, trackIndex, animation._animation, loop ? -1 : 0, delay);
     if (entry.address == nullptr.address) throw Exception("Couldn't add animation ${animation.getName()}");
     return TrackEntry._(entry, this);
   }
 
-  /// Sets an empty animation for a track, discarding any queued animations, and mixes to it over the specified mix duration.
+  /// Sets an empty animation for a track at [trackIndex], discarding any queued animations, and sets the track entry's
+  /// [TrackEntry.getMixDuration] to [mixDuration]. An empty animation has no timelines and serves as a placeholder for mixing in or out.
+  ///
+  /// Mixing out is done by setting an empty animation with a mix duration using either [setEmptyAnimation],
+  /// [setEmptyAnimations], or [addEmptyAnimation]. Mixing to an empty animation causes
+  /// the previous animation to be applied less and less over the mix duration. Properties keyed in the previous animation
+  /// transition to the value from lower tracks or to the setup pose value if no lower tracks key the property. A mix duration of
+  /// 0 still mixes out over one frame.
+  ///
+  /// Mixing in is done by first setting an empty animation, then adding an animation using
+  /// [addAnimation] with the desired delay (an empty animation has a duration of 0) and on
+  /// the returned track entry, set the [TrackEntry.setMixDuration]. 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.
   TrackEntry setEmptyAnimation(int trackIndex, double mixDuration) {
     final entry = _bindings.spine_animation_state_set_empty_animation(_state, trackIndex, mixDuration);
     return TrackEntry._(entry, this);
   }
 
-  /// Adds an empty animation to be played after the current or last queued animation for a track, and mixes to it over the
+  /// Adds an empty animation to be played after the current or last queued animation for a track, and sets the track entry's
-  /// specified mix duration.
+  /// [TrackEntry.getMixDuration]. If the track is empty, it is equivalent to calling
-  /// @return
+  /// [setEmptyAnimation].
-  /// A track entry to allow further customization of animation playback. References to the track entry must not be kept after AnimationState.Dispose.
   ///
-  /// @param trackIndex Track number.
+  /// See [setEmptyAnimation].
-  /// @param mixDuration Mix duration.
+  ///
-  /// @param delay Seconds to begin this animation after the start of the previous animation. May be &lt;= 0 to use the animation
+  /// If [delay] > 0, sets [TrackEntry.getDelay]. If <= 0, the delay set is the duration of the previous track entry
-  /// duration of the previous track minus any mix duration plus the negative delay.
+  /// minus any mix duration plus the specified <code>delay</code> (ie the mix ends at (<code>delay</code> = 0) or
+  /// before (<code>delay</code> < 0) the previous track entry duration). If the previous entry is looping, its next
+  /// loop completion is used instead of its duration.
+  ///
+  /// Returns a track entry to allow further customization of animation playback. References to the track entry must not be kept
+  /// after the [EventType.dispose] event occurs.
   TrackEntry addEmptyAnimation(int trackIndex, double mixDuration, double delay) {
     final entry = _bindings.spine_animation_state_add_empty_animation(_state, trackIndex, mixDuration, delay);
     return TrackEntry._(entry, this);
   }
 
+  /// Returns the track entry for the animation currently playing on the track, or null if no animation is currently playing.
   TrackEntry? getCurrent(int trackIndex) {
     final entry = _bindings.spine_animation_state_get_current(_state, trackIndex);
     if (entry.address == nullptr.address) return null;
     return TrackEntry._(entry, this);
   }
 
+  /// Returns the number of tracks that have animations queued.
   int getNumTracks() {
     return _bindings.spine_animation_state_get_num_tracks(_state);
   }
 
-  /// Sets an empty animation for every track, discarding any queued animations, and mixes to it over the specified mix duration.
+  /// Sets an empty animation for every track, discarding any queued animations, and mixes to it over the specified mix
+  /// duration.
   void setEmptyAnimations(double mixDuration) {
     _bindings.spine_animation_state_set_empty_animations(_state, mixDuration);
   }
 
+  /// Multiplier for the delta time when the animation state is updated, causing time for all animations and mixes to play slower
+  /// or faster. Defaults to 1.
+  ///
+  /// See [TrackEntry.getTimeScale] for affecting a single animation.
   double getTimeScale() {
     return _bindings.spine_animation_state_get_time_scale(_state);
   }
@@ -3714,10 +3827,15 @@ class AnimationState {
     _bindings.spine_animation_state_set_time_scale(_state, timeScale);
   }
 
+  /// The [AnimationStateData] to look up mix durations.
   AnimationStateData getData() {
     return AnimationStateData._(_bindings.spine_animation_state_get_data(_state));
   }
 
+  /// The listener for events generated for all tracks managed by the AnimationState, or null.
+  ///
+  /// A track entry returned from [setAnimation] is already the current animation
+  /// for the track, so the track entry listener will not be called for [EventType.start].
   void setListener(AnimationStateListener? listener) {
     _stateListener = listener;
   }

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

@@ -847,7 +847,7 @@ public class AnimationState {
 		this.timeScale = timeScale;
 	}
 
-	/** The AnimationStateData to look up mix durations. */
+	/** The {@link AnimationStateData} to look up mix durations. */
 	public AnimationStateData getData () {
 		return data;
 	}
@@ -1199,13 +1199,13 @@ public class AnimationState {
 		}
 
 		/** The track entry for the previous animation when mixing from the previous animation to this animation, or null if no
-		 * mixing is currently occuring. When mixing from multiple animations, <code>mixingFrom</code> makes up a linked list. */
+		 * mixing is currently occurring. When mixing from multiple animations, <code>mixingFrom</code> makes up a linked list. */
 		public @Null TrackEntry getMixingFrom () {
 			return mixingFrom;
 		}
 
 		/** The track entry for the next animation when mixing from this animation to the next animation, or null if no mixing is
-		 * currently occuring. When mixing to multiple animations, <code>mixingTo</code> makes up a linked list. */
+		 * currently occurring. When mixing to multiple animations, <code>mixingTo</code> makes up a linked list. */
 		public @Null TrackEntry getMixingTo () {
 			return mixingTo;
 		}