Improve docs and +getRotationOrder()

Author: CryptoMorin

src/main/java/com/cryptomorin/xseries/particles/ParticleDisplay.java

@@ -44,13 +44,19 @@
 import java.util.function.Supplier;
 
 /**
- * By default the particle xyz offsets and speed aren't 0, but
+ * Represents how particles should be spawned. The simplest use case would be the following code
+ * which spawns a single particle in front of the player:
+ * <pre>{@code
+ * ParticleDisplay.of(Particle.FLAME).spawn(player.getEyeLocation());
+ * }</pre>
+ * This class is disposable by {@link XParticle} methods.
+ * It should not be used across multiple methods. I.e. it should not be
+ * used even to spawn a simple particle after it was used by one of {@link XParticle} methods.
+ * <p>
+ * By default, the particle xyz offsets and speed aren't 0, but
  * everything will be 0 by default in this class.
  * Particles are spawned to a location. So all the nearby players can see it.
  * <p>
- * The fields of this class are publicly accessible for ease of use.
- * All the fields can be null except the particle type.
- * <p>
  * For cross-version compatibility, instead of Bukkit's {@link org.bukkit.Color}
  * the java awt {@link Color} class is used.
  * <p>
@@ -60,7 +66,7 @@
  * <code>[r, g, b, size]</code>
  *
  * @author Crypto Morin
- * @version 8.0.0
+ * @version 8.1.0
  * @see XParticle
  */
 public class ParticleDisplay implements Cloneable {
@@ -100,6 +106,11 @@ public class ParticleDisplay implements Cloneable {
      */
     private final Vector directionNormal = new Vector(0, 1, 0);
     private Supplier<Vector> direction = () -> directionNormal;
+    /**
+     * The xyz axis order of how the particle's matrix should be rotated.
+     * Yes, it matters which axis you rotate first as it'll have an impact on the
+     * other rotations.
+     */
     @Nonnull
     private Axis[] rotationOrder = DEFAULT_ROTATION_ORDER;
     @Nullable
@@ -505,6 +516,7 @@ public static Vector rotateAround(@Nonnull Vector location, double x, double y,
 
     /**
      * Rotates the given location vector around a certain axis.
+     * It simply uses the <a href="https://en.wikipedia.org/wiki/Rotation_matrix">rotation matrix</a>.
      *
      * @param location the location to rotate.
      * @param axis     the axis to rotate the location around.
@@ -840,10 +852,7 @@ public ParticleDisplay withLocationCaller(@Nullable Callable<Location> locationC
     }
 
     /**
-     * Sets the rotation order that the particles should be rotated.
-     * Yes,it matters which axis you rotate first as it'll have an impact on the
-     * other rotations.
-     *
+     * @see #rotationOrder
      * @since 7.0.0
      */
     public ParticleDisplay rotationOrder(@Nonnull Axis first, @Nonnull Axis second, @Nonnull Axis third) {
@@ -855,8 +864,21 @@ public ParticleDisplay rotationOrder(@Nonnull Axis first, @Nonnull Axis second,
         return this;
     }
 
+    /**
+     * This array should not be modified directed at all. Use {@link #rotationOrder(Axis, Axis, Axis)} instead.
+     * @see #rotationOrder
+     * @since 8.1.0
+     */
+    @Nonnull
+    public Axis[] getRotationOrder() {
+        return rotationOrder;
+    }
+
     /**
      * Gets the location of an entity if specified or the constant location.
+     * <p>
+     * This method is usually the center of the shape if the algorithm which uses
+     * it supports the use of {@link #advanceInDirection(double)}.
      *
      * @return the location of the particle.
      * @since 3.1.0
@@ -1054,6 +1076,7 @@ public ParticleDisplay cloneWithLocation(double x, double y, double z) {
     public ParticleDisplay clone() {
         ParticleDisplay display = ParticleDisplay.of(particle)
                 .withLocationCaller(locationCaller)
+                .withDirection(direction)
                 .withCount(count).offset(offset.clone())
                 .forceSpawn(force).onSpawn(onSpawn);