1 files changed, 23 insertions, 7 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java b/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java
index 3ee504a29..d7e72e245 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java
@@ -888,25 +888,35 @@ public final class VectorUtil {
         return triAreaVec2(a,b,c) > 0;
     }
 
-    /** Compute the winding of given points
+    /**
+     * Compute the winding of the 3 given points
+     * <p>
+     * Consider using {@link #getWinding(ArrayList)} using the {@link #area(ArrayList)} function over all points
+     * on complex shapes for a reliable result!
+     * </p>
      * @param a first vertex
      * @param b second vertex
      * @param c third vertex
-     * @return Winding
+     * @return {@link Winding#CCW} or {@link Winding#CW}
+     * @see #getWinding(ArrayList)
      */
     public static Winding getWinding(final Vert2fImmutable a, final Vert2fImmutable b, final Vert2fImmutable c) {
         return triAreaVec2(a,b,c) > 0 ? Winding.CCW : Winding.CW ;
     }
 
-    /** Computes the area of a list of vertices to check if ccw
+    /**
+     * Computes the area of a list of vertices.
+     * <p>
+     * This method is utilized e.g. to reliably compute the {@link Winding} of complex shapes.
+     * </p>
      * @param vertices
      * @return positive area if ccw else negative area value
+     * @see #getWinding(ArrayList)
      */
     public static float area(final ArrayList<? extends Vert2fImmutable> vertices) {
         final int n = vertices.size();
         float area = 0.0f;
-        for (int p = n - 1, q = 0; q < n; p = q++)
-        {
+        for (int p = n - 1, q = 0; q < n; p = q++) {
             final float[] pCoord = vertices.get(p).getCoord();
             final float[] qCoord = vertices.get(q).getCoord();
             area += pCoord[0] * qCoord[1] - qCoord[0] * pCoord[1];
@@ -914,9 +924,15 @@ public final class VectorUtil {
         return area;
     }
 
-    /** Compute the  general winding of the vertices
+    /**
+     * Compute the winding using the {@link #area(ArrayList)} function over all vertices for complex shapes.
+     * <p>
+     * Uses the {@link #area(ArrayList)} function over all points
+     * on complex shapes for a reliable result!
+     * </p>
      * @param vertices array of Vertices
-     * @return CCW or CW {@link Winding}
+     * @return {@link Winding#CCW} or {@link Winding#CW}
+     * @see #area(ArrayList)
      */
     public static Winding getWinding(final ArrayList<? extends Vert2fImmutable> vertices) {
         return area(vertices) >= 0 ? Winding.CCW : Winding.CW ;