improve the TransformTrack javadoc (#1642)

* TransformTrack:  don't imply that the target must be a bone

* TransformTrack:  don't imply that the track must be a joint track

* TransformTrack:  delete mentions of "this track" from the javadoc

* TransformTrack:  do getters return internal arrays or copies?

* TransformTrack:  consistent verb forms and better grammar in javadoc

* TransformTrack:  no need to mention that "times" is a float array

* TransformTrack:  mention that setTimes() creates an alias

* TransformTrack:  document arguments that can be null

* TransformTrack:  clearer descriptions of the class and its fields

* "frame" -> "keyframe", in case it's unclear they're the same thing

* document where argument length must be the same as times.length

* TransformTrack:  summary fragments shouldn't form a complete sentence

* TransformTrack:  capitalize and punctuate the summary fragments

* TransformTrack:  indent block-tag continuation lines

Author: stephengold

jme3-core/src/main/java/com/jme3/anim/TransformTrack.java

@@ -42,22 +42,23 @@
 import java.io.IOException;
 
 /**
- * Contains a list of transforms and times for each keyframe.
+ * An AnimTrack that transforms a Joint or Spatial
+ * using a list of transforms and times for keyframes.
  *
  * @author Rémy Bouquet
  */
 public class TransformTrack implements AnimTrack<Transform> {
 
     private double length;
+    private FrameInterpolator interpolator = FrameInterpolator.DEFAULT;
     private HasLocalTransform target;
 
     /**
-     * Transforms and times for track.
+     * Transforms and times for keyframes.
      */
     private CompactVector3Array translations;
     private CompactQuaternionArray rotations;
     private CompactVector3Array scales;
-    private FrameInterpolator interpolator = FrameInterpolator.DEFAULT;
     private float[] times;
 
     /**
@@ -67,39 +68,42 @@ protected TransformTrack() {
     }
 
     /**
-     * Creates a transform track for the given bone index
+     * Creates a transform track for the given target.
      *
      * @param target       the target Joint or Spatial of the new track
-     * @param times        a float array with the time of each frame
-     * @param translations the translation of the bone for each frame
-     * @param rotations    the rotation of the bone for each frame
-     * @param scales       the scale of the bone for each frame
+     * @param times        the time for each keyframe, or null for none
+     * @param translations the translation of the target for each keyframe
+     *                     (same length as times) or null for no translation
+     * @param rotations    the rotation of the target for each keyframe
+     *                     (same length as times) or null for no rotation
+     * @param scales       the scale of the target for each keyframe
+     *                     (same length as times) or null for no scaling
      */
     public TransformTrack(HasLocalTransform target, float[] times, Vector3f[] translations, Quaternion[] rotations, Vector3f[] scales) {
         this.target = target;
         this.setKeyframes(times, translations, rotations, scales);
     }
 
     /**
-     * return the array of rotations of this track
+     * Copies the rotations.
      *
-     * @return an array, or null if no rotations
+     * @return a new array, or null if no rotations
      */
     public Quaternion[] getRotations() {
         return rotations == null ? null : rotations.toObjectArray();
     }
 
     /**
-     * returns the array of scales for this track
+     * Copies the scales.
      *
-     * @return an array or null
+     * @return a new array, or null if no scales
      */
     public Vector3f[] getScales() {
         return scales == null ? null : scales.toObjectArray();
     }
 
     /**
-     * returns the arrays of time for this track
+     * Gives access to the keyframe times.
      *
      * @return the pre-existing array
      */
@@ -108,19 +112,19 @@ public float[] getTimes() {
     }
 
     /**
-     * returns the array of translations of this track
+     * Copies the translations.
      *
-     * @return an array, or null if no translations
+     * @return a new array, or null if no translations
      */
     public Vector3f[] getTranslations() {
         return translations == null ? null : translations.toObjectArray();
     }
 
 
     /**
-     * Sets the keyframes times for this Joint track
+     * Sets the keyframe times.
      *
-     * @param times the keyframes times
+     * @param times the desired keyframe times (alias created, not null, not empty)
      */
     public void setTimes(float[] times) {
         if (times == null || times.length == 0) {
@@ -132,9 +136,10 @@ public void setTimes(float[] times) {
     }
 
     /**
-     * Set the translations for this joint track
+     * Sets the translations.
      *
-     * @param translations the translation of the bone for each frame
+     * @param translations the desired translation of the target for each
+     *     keyframe (not null, same length as "times")
      */
     public void setKeyframesTranslation(Vector3f[] translations) {
         if (times == null) {
@@ -154,9 +159,10 @@ public void setKeyframesTranslation(Vector3f[] translations) {
     }
 
     /**
-     * Set the scales for this joint track
+     * Sets the scales.
      *
-     * @param scales the scales of the bone for each frame
+     * @param scales the desired scale of the target for each keyframe (not
+     *     null, same length as "times")
      */
     public void setKeyframesScale(Vector3f[] scales) {
         if (times == null) {
@@ -176,9 +182,10 @@ public void setKeyframesScale(Vector3f[] scales) {
     }
 
     /**
-     * Set the rotations for this joint track
+     * Sets the rotations.
      *
-     * @param rotations the rotations of the bone for each frame
+     * @param rotations the desired rotation of the target for each keyframe
+     *     (not null, same length as "times")
      */
     public void setKeyframesRotation(Quaternion[] rotations) {
         if (times == null) {
@@ -199,12 +206,19 @@ public void setKeyframesRotation(Quaternion[] rotations) {
 
 
     /**
-     * Set the translations, rotations and scales for this bone track
+     * Sets the translations, rotations, and/or scales.
      *
-     * @param times        a float array with the time of each frame
-     * @param translations the translation of the bone for each frame
-     * @param rotations    the rotation of the bone for each frame
-     * @param scales       the scale of the bone for each frame
+     * @param times        the desired time for each keyframe,
+     *                     or null to leave the times unchanged
+     * @param translations the desired translation of the target for each
+     *                     keyframe (same length as times)
+     *                     or null to leave the translations unchanged
+     * @param rotations    the desired rotation of the target for each keyframe
+     *                     (same length as times)
+     *                     or null to leave the rotations unchanged
+     * @param scales       the desired scale of the target for each keyframe
+     *                     (same length as times)
+     *                     or null to leave the scales unchanged
      */
     public void setKeyframes(float[] times, Vector3f[] translations, Quaternion[] rotations, Vector3f[] scales) {
         if (times != null) {
@@ -248,7 +262,7 @@ public void getDataAtTime(double t, Transform transform) {
         int endFrame = 1;
         float blend = 0;
         if (time >= times[lastFrame]) {
-            // extrapolate beyond the final frame of the animation
+            // extrapolate beyond the final keyframe of the animation
             startFrame = lastFrame;
 
             float inferredInterval = times[lastFrame] - times[lastFrame - 1];
@@ -281,7 +295,7 @@ public void getDataAtTime(double t, Transform transform) {
     }
 
     /**
-     * Replace the frame interpolator.
+     * Replaces the frame interpolator.
      *
      * @param interpolator the interpolator to use (alias created)
      */
@@ -290,8 +304,7 @@ public void setFrameInterpolator(FrameInterpolator interpolator) {
     }
 
     /**
-     * Access the target affected by this track, which might be a Joint or a
-     * Spatial.
+     * Gives access to the target, which might be a Joint or a Spatial.
      *
      * @return the pre-existing instance
      */
@@ -300,7 +313,7 @@ public HasLocalTransform getTarget() {
     }
 
     /**
-     * Replace the target of this track, which might be a Joint or a Spatial.
+     * Replaces the target, which might be a Joint or a Spatial.
      *
      * @param target the target to use (alias created)
      */
@@ -309,7 +322,7 @@ public void setTarget(HasLocalTransform target) {
     }
 
     /**
-     * Serialize this track to the specified exporter, for example when
+     * Serializes this track to the specified exporter, for example when
      * saving to a J3O file.
      *
      * @param ex the exporter to write to (not null)
@@ -326,7 +339,7 @@ public void write(JmeExporter ex) throws IOException {
     }
 
     /**
-     * De-serialize this track from the specified importer, for example when
+     * De-serializes this track from the specified importer, for example when
      * loading from a J3O file.
      *
      * @param im the importer to read from (not null)