From da67bda3a4e230b7ff87ac209db3fa1b8b5f587f Mon Sep 17 00:00:00 2001
From: Quentin Legot <legotquentin@gmail.com>
Date: Tue, 13 Apr 2021 18:07:59 +0200
Subject: [PATCH] add comment to methods in AbstractCanvas.java and fix some

---
 src/lsystem/engine/Parser.java              |  2 +-
 src/lsystem/screen/gl3d/AbstractCanvas.java | 30 +++++++++++++++++++++
 src/lsystem/utils/Pair.java                 |  7 +++--
 3 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/src/lsystem/engine/Parser.java b/src/lsystem/engine/Parser.java
index ffffddb..7b9e4fe 100644
--- a/src/lsystem/engine/Parser.java
+++ b/src/lsystem/engine/Parser.java
@@ -162,7 +162,7 @@ public class Parser {
 
     /**
      * Add some pre condition before execute {@link Float#parseFloat(String)} like if {@code number} give a {@code +}
-     * or an empty {@link String}, method will return 0.25° and {@code -} will return 0.25°
+     * or an empty {@link String}, method will return 0.25 degrees and {@code -} will return 25 degrees
      * @param number the number which will be converted
      * @return the converted float from {@code number} param
      * @throws NumberFormatException throw by {@link Float#parseFloat(String)}
diff --git a/src/lsystem/screen/gl3d/AbstractCanvas.java b/src/lsystem/screen/gl3d/AbstractCanvas.java
index 0d9ae9e..42db1ae 100644
--- a/src/lsystem/screen/gl3d/AbstractCanvas.java
+++ b/src/lsystem/screen/gl3d/AbstractCanvas.java
@@ -18,15 +18,28 @@ import java.awt.event.WindowAdapter;
 import java.awt.event.WindowEvent;
 import java.util.List;
 
+/**
+ * create an instance of the 3D window
+ */
 public abstract class AbstractCanvas {
 
     private Element lSystem;
+    /**
+     * If value is {@link State#LOAD}, we currently converting the L-System to {@link Element} object
+     * otherwise the value is {@link State#FINISH_OR_NULL} 2 possibility:
+     *      we waiting for end-user to give axiom and rules from {@link lsystem.screen.main.MainFrame main window}
+     *      or we window is open and user see the representation the L-System in 3D
+     * @see State
+     */
     public State parsedState = State.FINISH_OR_NULL;
     public JFrame frame;
     protected FPSAnimator animator;
     public final GLCanvas glCanvas;
     public GLU glu = new GLU();
     public GLUT glut = new GLUT();
+    /**
+     * camera position, 6 dimension tab with respectively x, y and z camera pos and yaw, pitch roll camera rotation
+     */
     public float[] camera = {0f, 1f, 5f, // camera pos x,y, z
             0f, 0f, 0f}; // camera rotation yaw(x-axis), pitch(y-axis), roll(z-axis)
 
@@ -44,6 +57,9 @@ public abstract class AbstractCanvas {
                 setVisible(false);
                 lSystem = null;
                 parsedState = State.FINISH_OR_NULL;
+                // after setting lSystem to null, the object can be large (up to 4gb during our tests) and it's stored
+                // long time in memory
+                // the partial gc only clear the object itself and absolutely not all of its children from memory
                 System.gc();
             }
         });
@@ -54,6 +70,10 @@ public abstract class AbstractCanvas {
 
     protected abstract void addEventsListeners();
 
+    /**
+     * if {@code bl} is true, we start the animator and then display the window
+     * @param bl
+     */
     public void setVisible(boolean bl) {
         if(bl)
             animator.start();
@@ -66,12 +86,22 @@ public abstract class AbstractCanvas {
         return lSystem;
     }
 
+    /**
+     * get axiom and rule to rewrite and parse it to an {@link Element} object and store it in {@link AbstractCanvas#lSystem}
+     * @param axiom give from {@link lsystem.screen.main.Tab}
+     * @param rules same
+     * @param iterations same
+     * @throws NumberFormatException throw by {@link Float#parseFloat(String)}
+     */
     public void setLSystem(String axiom, List<Pair<String, String>> rules, int iterations) throws NumberFormatException {
         parsedState = State.LOAD;
         this.lSystem = Parser.parse(Rewrite.rewrite(axiom, rules, iterations));
         parsedState = State.FINISH_OR_NULL;
     }
 
+    /**
+     * @see AbstractCanvas#parsedState
+     */
     public enum State {
         LOAD,
         FINISH_OR_NULL
diff --git a/src/lsystem/utils/Pair.java b/src/lsystem/utils/Pair.java
index 313b7a8..f7b7328 100644
--- a/src/lsystem/utils/Pair.java
+++ b/src/lsystem/utils/Pair.java
@@ -3,10 +3,9 @@ package lsystem.utils;
 import java.util.Objects;
 
 /**
- * tuple containing 2 unknown type elements
- *
- * @param <U> left
- * @param <K> right
+ * tuple containing 2 generic type elements
+ * @param <U> left side
+ * @param <K> right side
  */
 public class Pair<U, K> {