From d56c9c3564a5baf46517a2f9ecaa026a9fa6155d Mon Sep 17 00:00:00 2001
From: zyno1 <olivierzeyen@gmail.com>
Date: Tue, 9 Apr 2019 10:46:14 +0200
Subject: [PATCH] doc
---
src/main/java/complexityparser/Model.java | 16 +++++++-
.../listener/BaseListener.java | 3 ++
.../complexityparser/listener/TOSBuilder.java | 23 +++++++++++
src/main/java/complexityparser/tos/Block.java | 37 +++++++++++++++++
src/main/java/complexityparser/tos/TOS.java | 40 +++++++++++++++++++
.../java/complexityparser/tos/symbols/ID.java | 7 ++++
.../complexityparser/tos/symbols/Symbol.java | 11 +++++
.../tos/symbols/VariableID.java | 3 ++
.../tos/symbols/VariableSymbol.java | 3 ++
src/main/java/lib/Observable.java | 18 +++++++++
src/main/java/lib/Observer.java | 3 ++
src/main/java/view/EditorView.java | 3 ++
src/main/java/view/MainFrame.java | 6 +++
src/main/java/view/TreePanel.java | 3 ++
14 files changed, 175 insertions(+), 1 deletion(-)
diff --git a/src/main/java/complexityparser/Model.java b/src/main/java/complexityparser/Model.java
index b848723..32b535e 100644
--- a/src/main/java/complexityparser/Model.java
+++ b/src/main/java/complexityparser/Model.java
@@ -3,7 +3,6 @@ package complexityparser;
import complexityparser.analyse.antlr.Java8Lexer;
import complexityparser.analyse.antlr.Java8Listener;
import complexityparser.analyse.antlr.Java8Parser;
-import complexityparser.listener.BaseListener;
import complexityparser.listener.TOSBuilder;
import complexityparser.tos.TOS;
import lib.Observable;
@@ -17,6 +16,9 @@ import org.antlr.v4.runtime.tree.ParseTreeWalker;
import java.awt.*;
import java.util.Arrays;
+/**
+ * this class contains the code to be analysed by ANTLR and the resulting parser.lexer and tree
+ */
public class Model extends Observable {
private String code;
private Java8Lexer lexer;
@@ -34,6 +36,10 @@ public class Model extends Observable {
setCode(code);
}
+ /**
+ *
+ * @return a java swing component representing a graphical view of the ANTLR generated tree
+ */
public TreeViewer getTreeComponent() {
TreeViewer viewer = new TreeViewer(Arrays.asList(parser.getRuleNames()), context);
@@ -43,6 +49,10 @@ public class Model extends Observable {
return viewer;
}
+ /**
+ * changes the code string that has to be analysed and analyses the code (generates a new ANTLR tree)
+ * @param code
+ */
public void setCode(String code) {
this.code = code;
@@ -63,6 +73,10 @@ public class Model extends Observable {
update();
}
+ /**
+ *
+ * @return the code that has been analysed by ANTLR
+ */
public String getCode() {
return code;
}
diff --git a/src/main/java/complexityparser/listener/BaseListener.java b/src/main/java/complexityparser/listener/BaseListener.java
index 0bb7513..d854a3b 100644
--- a/src/main/java/complexityparser/listener/BaseListener.java
+++ b/src/main/java/complexityparser/listener/BaseListener.java
@@ -3,6 +3,9 @@ package complexityparser.listener;
import complexityparser.analyse.antlr.Java8BaseListener;
import complexityparser.analyse.antlr.Java8Parser;
+/**
+ * basically useless
+ */
public class BaseListener extends Java8BaseListener {
public BaseListener() {
}
diff --git a/src/main/java/complexityparser/listener/TOSBuilder.java b/src/main/java/complexityparser/listener/TOSBuilder.java
index cafd33d..00c22db 100644
--- a/src/main/java/complexityparser/listener/TOSBuilder.java
+++ b/src/main/java/complexityparser/listener/TOSBuilder.java
@@ -6,6 +6,9 @@ import complexityparser.tos.TOS;
import complexityparser.tos.symbols.VariableID;
import complexityparser.tos.symbols.VariableSymbol;
+/**
+ * a basic listener (visitor) that will walk the ANTLR generated tree and fill the TOS with the appropriate symbols
+ */
public class TOSBuilder extends Java8BaseListener {
private TOS tos;
@@ -15,6 +18,10 @@ public class TOSBuilder extends Java8BaseListener {
tos.clear();
}
+ /**
+ * entering a Method declaration
+ * @param ctx
+ */
@Override
public void enterMethodDeclaration(Java8Parser.MethodDeclarationContext ctx) {
super.enterMethodDeclaration(ctx);
@@ -24,6 +31,10 @@ public class TOSBuilder extends Java8BaseListener {
tos.enterBlock(name);
}
+ /**
+ * exiting a block (class Blocks are seperate, I'm not sure why)
+ * @param ctx
+ */
@Override
public void exitBlock(Java8Parser.BlockContext ctx) {
super.exitBlock(ctx);
@@ -31,6 +42,10 @@ public class TOSBuilder extends Java8BaseListener {
tos.exitBlock();
}
+ /**
+ * entering a class Block
+ * @param ctx
+ */
@Override
public void enterClassDeclaration(Java8Parser.ClassDeclarationContext ctx) {
super.enterClassDeclaration(ctx);
@@ -40,6 +55,10 @@ public class TOSBuilder extends Java8BaseListener {
tos.enterBlock(name);
}
+ /**
+ * exiting a class Block
+ * @param ctx
+ */
@Override
public void exitClassBody(Java8Parser.ClassBodyContext ctx) {
super.exitClassBody(ctx);
@@ -47,6 +66,10 @@ public class TOSBuilder extends Java8BaseListener {
tos.exitBlock();
}
+ /**
+ * entering a variable declaration
+ * @param ctx
+ */
@Override
public void enterLocalVariableDeclaration(Java8Parser.LocalVariableDeclarationContext ctx) {
String tier = ctx.Tier().getText();
diff --git a/src/main/java/complexityparser/tos/Block.java b/src/main/java/complexityparser/tos/Block.java
index 6afae46..485925a 100644
--- a/src/main/java/complexityparser/tos/Block.java
+++ b/src/main/java/complexityparser/tos/Block.java
@@ -7,6 +7,16 @@ import java.util.HashMap;
import java.util.Map;
import java.util.Set;
+/**
+ * a class representing a block
+ * it contains:
+ * - the name of the block
+ * - the number of the block
+ * - the parent number of the block
+ * - a hashmap containing every <ID, Symbol> pair (ID has to be unique)
+ *
+ * the class should not be instanced outside of the TOS class
+ */
public class Block {
private String name;
private int no;
@@ -30,26 +40,53 @@ public class Block {
symbols = new HashMap<>();
}
+ /**
+ * puts a new entry into a block
+ * every ID has to be unique inside a block, no check is done before or after inserting the ID so if an ID is redefined it will be overwritten without warning
+ * @param i the identifier of the entry
+ * @param s the symbol of the entry
+ */
public void put(ID i, Symbol s) {
symbols.put(i, s);
}
+ /**
+ *
+ * @param i
+ * @return the associated Symbol of the given ID (if the ID exists)
+ */
public Symbol get(ID i) {
return symbols.get(i);
}
+ /**
+ *
+ * @return the number of the parent block
+ */
public int getNoParent() {
return noParent;
}
+ /**
+ *
+ * @return the name of this block
+ */
public String getName() {
return name;
}
+ /**
+ *
+ * @return the number of this block
+ */
public int getNo() {
return no;
}
+ /**
+ *
+ * @return a Set containing the <ID, Symbol> pairs
+ */
public Set<Map.Entry<ID, Symbol>> getMap() {
return symbols.entrySet();
}
diff --git a/src/main/java/complexityparser/tos/TOS.java b/src/main/java/complexityparser/tos/TOS.java
index 036c4d2..470a051 100644
--- a/src/main/java/complexityparser/tos/TOS.java
+++ b/src/main/java/complexityparser/tos/TOS.java
@@ -7,12 +7,21 @@ import java.util.ArrayList;
import java.util.Map;
import java.util.Stack;
+/**
+ * Table Of Symbols
+ *
+ * it regroups all the variables with their tier type
+ */
public class TOS {
private static TOS tos = null;
private ArrayList<Block> array;
private int currentBlock;
+ /**
+ *
+ * @return the single instance that is available in the entire program
+ */
public static TOS getInstance() {
if(tos == null) {
tos = new TOS();
@@ -25,33 +34,61 @@ public class TOS {
clear();
}
+ /**
+ * clears the TOS and initlialises it with the <root> block (0)
+ */
public void clear() {
array.clear();
currentBlock = 0;
array.add(new Block("<root>", 0, 0));
}
+ /**
+ * enters a new block/ creates a new block
+ * @param name the name of the block
+ */
public void enterBlock(String name) {
array.add(new Block(name));
currentBlock = array.size() - 1;
}
+ /**
+ * exits the current block ant returns to the parrent
+ */
public void exitBlock() {
currentBlock = array.get(currentBlock).getNoParent();
}
+ /**
+ *
+ * @return the number of the current block
+ */
public int getCurrentBlock() {
return currentBlock;
}
+ /**
+ * puts a new entry into the current block
+ * every ID has to be unique inside the current block, no check is done before or after inserting the ID so if an ID is redefined it will be overwritten without warning
+ * @param i the identifier of the entry
+ * @param s the symbol of the entry
+ */
public void put(ID i, Symbol s) {
array.get(currentBlock).put(i, s);
}
+ /**
+ *
+ * @return the number which will be associatet to the next block which is the number of blocks as well (the size of the array)
+ */
public int getNextBlockNumber() {
return array.size();
}
+ /**
+ *
+ * @return a string representation of the TOS
+ */
public String toString() {
StringBuilder str = new StringBuilder();
@@ -102,6 +139,9 @@ public class TOS {
return str.toString();
}
+ /**
+ * just a simple class to make the toString function class work
+ */
private class Pair {
public Block b;
public int index;
diff --git a/src/main/java/complexityparser/tos/symbols/ID.java b/src/main/java/complexityparser/tos/symbols/ID.java
index c47ed95..4f44203 100644
--- a/src/main/java/complexityparser/tos/symbols/ID.java
+++ b/src/main/java/complexityparser/tos/symbols/ID.java
@@ -1,5 +1,8 @@
package complexityparser.tos.symbols;
+/**
+ * an abstract class to represent an ID
+ */
public abstract class ID {
private String name;
@@ -7,6 +10,10 @@ public abstract class ID {
this.name = name;
}
+ /**
+ *
+ * @return the name of the ID
+ */
public String getName() {
return name;
}
diff --git a/src/main/java/complexityparser/tos/symbols/Symbol.java b/src/main/java/complexityparser/tos/symbols/Symbol.java
index f884873..18f09ee 100644
--- a/src/main/java/complexityparser/tos/symbols/Symbol.java
+++ b/src/main/java/complexityparser/tos/symbols/Symbol.java
@@ -2,6 +2,9 @@ package complexityparser.tos.symbols;
import complexityparser.tos.TOS;
+/**
+ * an abstract class to represent a Symbol
+ */
public abstract class Symbol {
private int tier;
private int noBlock;
@@ -11,10 +14,18 @@ public abstract class Symbol {
noBlock = TOS.getInstance().getCurrentBlock();
}
+ /**
+ *
+ * @return the tier type of this symbol
+ */
public int getTier() {
return tier;
}
+ /**
+ *
+ * @return the block number in which this Symbol can be found
+ */
public int getNoBlock() {
return noBlock;
}
diff --git a/src/main/java/complexityparser/tos/symbols/VariableID.java b/src/main/java/complexityparser/tos/symbols/VariableID.java
index ca9c6e8..440a639 100644
--- a/src/main/java/complexityparser/tos/symbols/VariableID.java
+++ b/src/main/java/complexityparser/tos/symbols/VariableID.java
@@ -1,5 +1,8 @@
package complexityparser.tos.symbols;
+/**
+ * a specific ID to represent Variables
+ */
public class VariableID extends ID {
public VariableID(String name) {
super(name);
diff --git a/src/main/java/complexityparser/tos/symbols/VariableSymbol.java b/src/main/java/complexityparser/tos/symbols/VariableSymbol.java
index 88f2714..d5391c8 100644
--- a/src/main/java/complexityparser/tos/symbols/VariableSymbol.java
+++ b/src/main/java/complexityparser/tos/symbols/VariableSymbol.java
@@ -1,5 +1,8 @@
package complexityparser.tos.symbols;
+/**
+ * a specific class to represent Variables
+ */
public class VariableSymbol extends Symbol {
public VariableSymbol(int tier) {
super(tier);
diff --git a/src/main/java/lib/Observable.java b/src/main/java/lib/Observable.java
index aa51fd1..788a6c9 100644
--- a/src/main/java/lib/Observable.java
+++ b/src/main/java/lib/Observable.java
@@ -2,21 +2,39 @@ package lib;
import java.util.ArrayList;
+/**
+ * a simple abstract class to make updating the GUI easier
+ */
public abstract class Observable {
private ArrayList<Observer> list;
+ /**
+ * every observer will be notified when the update method is called
+ * the Observer::update(...) method will be called an thus the GUI will be updated
+ */
public Observable() {
list = new ArrayList<>(2);
}
+ /**
+ * adds an observer to the list
+ * @param o
+ */
public void add(Observer o) {
list.add(o);
}
+ /**
+ * removes a component from the list
+ * @param o
+ */
public void remove(Observer o) {
list.remove(o);
}
+ /**
+ * notifies the observers so that they can update themselves
+ */
public void update() {
for(Observer o : list) {
o.update(this);
diff --git a/src/main/java/lib/Observer.java b/src/main/java/lib/Observer.java
index 9f543fe..310021f 100644
--- a/src/main/java/lib/Observer.java
+++ b/src/main/java/lib/Observer.java
@@ -1,5 +1,8 @@
package lib;
+/**
+ * a simple interface to make updating the GUI easier
+ */
public interface Observer {
void update(Observable m);
}
diff --git a/src/main/java/view/EditorView.java b/src/main/java/view/EditorView.java
index 50cbe0c..6ddfcba 100644
--- a/src/main/java/view/EditorView.java
+++ b/src/main/java/view/EditorView.java
@@ -12,6 +12,9 @@ import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
+/**
+ * a basic view to display a text editor containing the code that is analysed and displayed by the ANTLR tree
+ */
public class EditorView extends JPanel {
private JScrollPane panel;
diff --git a/src/main/java/view/MainFrame.java b/src/main/java/view/MainFrame.java
index c9f6e01..b16ebcd 100644
--- a/src/main/java/view/MainFrame.java
+++ b/src/main/java/view/MainFrame.java
@@ -5,6 +5,9 @@ import complexityparser.Model;
import javax.swing.*;
import java.awt.*;
+/**
+ * just the main window
+ */
public class MainFrame extends JFrame {
public MainFrame(Model m) {
setTheme();
@@ -23,6 +26,9 @@ public class MainFrame extends JFrame {
//setSize(600,600);
}
+ /**
+ * changes the look and feel of java swing to the OS theme
+ */
private static void setTheme() {
try {
UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
diff --git a/src/main/java/view/TreePanel.java b/src/main/java/view/TreePanel.java
index 9f0478e..f34ef8c 100644
--- a/src/main/java/view/TreePanel.java
+++ b/src/main/java/view/TreePanel.java
@@ -7,6 +7,9 @@ import lib.Observer;
import javax.swing.*;
import java.awt.*;
+/**
+ * a basic pannel displaying the ANTLR tree
+ */
public class TreePanel extends JScrollPane implements Observer {
public TreePanel(Model m) {
--
GitLab