GH-392 Make executable special type of statement, document and simpli…

…fy classes related to the runtime

panda-framework/src/main/java/org/panda_lang/framework/design/Failure.java

@@ -16,8 +16,18 @@
 
 package org.panda_lang.framework.design;
 
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents errors occurred in the framework
+ */
 public interface Failure {
 
-    String getNote();
+    /**
+     * Get additional information about the failure
+     *
+     * @return the note
+     */
+    @Nullable String getNote();
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/ControlledScope.java

@@ -21,8 +21,19 @@
 import org.panda_lang.framework.design.runtime.ProcessStack;
 import org.panda_lang.framework.design.runtime.Result;
 
+/**
+ * Scope that takes over control on the returned by process stack {@link org.panda_lang.framework.design.runtime.Result}
+ */
 public interface ControlledScope extends Scope {
 
+    /**
+     * Custom call called by the process
+     *
+     * @param stack the current stack
+     * @param instance the current instance
+     * @return result of invocation
+     * @throws Exception if something happen
+     */
     @Nullable Result<?> controlledCall(ProcessStack stack, Object instance) throws Exception;
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Controller.java

@@ -16,8 +16,16 @@
 
 package org.panda_lang.framework.design.architecture.dynamic;
 
+/**
+ * Specific type of statement that contains status code considered by the process of execution
+ */
 public interface Controller extends Executable {
 
-    byte getStatus();
+    /**
+     * Get represented status code
+     *
+     * @return the status code
+     */
+    byte getStatusCode();
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Executable.java

@@ -17,9 +17,13 @@
 package org.panda_lang.framework.design.architecture.dynamic;
 
 import org.jetbrains.annotations.Nullable;
+import org.panda_lang.framework.design.architecture.statement.Statement;
 import org.panda_lang.framework.design.runtime.ProcessStack;
 
-public interface Executable {
+/**
+ * Executable type of statement
+ */
+public interface Executable extends Statement {
 
     /**
      * Execute the statement

panda-framework/src/main/java/org/panda_lang/framework/design/architecture/dynamic/Frame.java

@@ -19,11 +19,17 @@
 import org.panda_lang.framework.design.architecture.statement.FramedScope;
 import org.panda_lang.framework.design.runtime.MemoryContainer;
 
+/**
+ * Specific type of memory container, associated with the {@link org.panda_lang.framework.design.architecture.statement.FramedScope}.
+ *
+ */
 public interface Frame extends MemoryContainer {
 
     /**
-     * @return the proper scope
+     * Get associated scope with the frame
+     *
+     * @return the frame scope
      */
-    FramedScope getScope();
+    FramedScope getFramedScope();
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/architecture/prototype/ReferenceFetchException.java

@@ -28,8 +28,4 @@ public ReferenceFetchException(String message) {
         super(message);
     }
 
-    public ReferenceFetchException(Throwable cause) {
-        super(cause);
-    }
-
 }

panda-framework/src/main/java/org/panda_lang/framework/design/runtime/MemoryContainer.java

@@ -18,6 +18,9 @@
 
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Represents segment of memory
+ */
 public interface MemoryContainer {
 
     /**
@@ -29,14 +32,16 @@ public interface MemoryContainer {
     @Nullable <T> T set(int pointer, @Nullable T value);
 
     /**
+     * Get value at the given position
+     *
      * @param pointer index of variable in current scope
-     * @return value
+     * @return the value at the given position
      */
     @Nullable <T> T get(int pointer);
 
     /**
-     * @return array length
+     * @return the size of memory
      */
-    int getAmountOfVariables();
+    int getMemorySize();
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Process.java

@@ -16,10 +16,13 @@
 
 package org.panda_lang.framework.design.runtime;
 
+/**
+ * Instance of application
+ */
 public interface Process {
 
     /**
-     * Execute the process
+     * Launch the process
      *
      * @return a result of the execution process
      */

panda-framework/src/main/java/org/panda_lang/framework/design/runtime/ProcessStack.java

@@ -22,16 +22,57 @@
 import org.panda_lang.framework.design.architecture.statement.Statement;
 import org.panda_lang.utilities.commons.function.ThrowingSupplier;
 
+/**
+ * Stack stores information about the active subroutines of a process
+ */
 public interface ProcessStack {
 
+    /**
+     * Call frame within the given instance
+     *
+     * @param instance the instance under which the frame has to be performed
+     * @param frame the frame to call
+     * @return result of invocation
+     * @throws Exception if something happen
+     */
     @Nullable Result<?> call(Object instance, Frame frame) throws Exception;
 
+    /**
+     * Call frame within the given instance and return custom result
+     *
+     * @param instance the instance within the frame has to be performed
+     * @param frame the frame to call
+     * @param resultSupplier the supplier of result
+     * @return result of invocation
+     * @throws Exception if something happen
+     */
     @Nullable Result<?> call(Object instance, Frame frame, ThrowingSupplier<Result<?>, Exception> resultSupplier) throws Exception;
 
+    /**
+     * Call scope within the given instance
+     *
+     * @param instance the instance within the frame has to performed
+     * @param scope the scope to call
+     * @return result of invocation
+     * @throws Exception if something happen
+     */
     @Nullable Result<?> call(Object instance, Scope scope) throws Exception;
 
+    /**
+     * Call statement within the given instance
+     *
+     * @param instance the instance within the statement
+     * @param statement the statement to call
+     * @return result of invocation
+     * @throws Exception if something happen
+     */
     @Nullable Result<?> call(Object instance, Statement statement) throws Exception;
 
+    /**
+     * Get statements on stack
+     *
+     * @return the array of statements on stack
+     */
     Statement[] getLivingFramesOnStack();
 
     /**

panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Result.java

@@ -18,6 +18,11 @@
 
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Result of invocation with status code
+ *
+ * @param <T> generic type of result
+ */
 public class Result<T> {
 
     private final byte status;
@@ -28,10 +33,21 @@ public Result(byte status, T result) {
         this.result = result;
     }
 
+    /**
+     * Get result value
+     *
+     * @return the value
+     */
     public @Nullable T getResult() {
         return result;
     }
 
+    /**
+     * Get status code
+     *
+     * @return the status code
+     * @see org.panda_lang.framework.design.runtime.Status
+     */
     public byte getStatus() {
         return status;
     }

panda-framework/src/main/java/org/panda_lang/framework/design/runtime/Status.java

@@ -16,14 +16,29 @@
 
 package org.panda_lang.framework.design.runtime;
 
+/**
+ * Default status codes
+ */
 public final class Status {
 
+    /**
+     * Represents thrown value
+     */
     public static final byte THROW = 0x00;
 
+    /**
+     * Represents returned value
+     */
     public static final byte RETURN = 0x01;
 
+    /**
+     * Represents break of scope on stack
+     */
     public static final byte BREAK = 0x02;
 
+    /**
+     * Represents omission of the rest of current scope on stack
+     */
     public static final byte CONTINUE = 0x03;
 
 }

panda-framework/src/main/java/org/panda_lang/framework/language/architecture/dynamic/AbstractExecutableStatement.java

@@ -17,11 +17,10 @@
 package org.panda_lang.framework.language.architecture.dynamic;
 
 import org.panda_lang.framework.design.architecture.dynamic.Executable;
-import org.panda_lang.framework.design.architecture.statement.Statement;
 import org.panda_lang.framework.design.interpreter.source.SourceLocation;
 import org.panda_lang.framework.language.architecture.statement.AbstractStatement;
 
-public abstract class AbstractExecutableStatement extends AbstractStatement implements Executable, Statement {
+public abstract class AbstractExecutableStatement extends AbstractStatement implements Executable {
 
     protected AbstractExecutableStatement(SourceLocation location) {
         super(location);

panda-framework/src/main/java/org/panda_lang/framework/language/architecture/dynamic/AbstractFrame.java

@@ -37,7 +37,7 @@ protected AbstractFrame(T frame) {
 
     private void checkIndex(int index) {
         if (index < 0 || index >= localMemory.length) {
-            throw new PandaRuntimeException("Invalid variable index: " + index + "; Amount of localMemory: " + getAmountOfVariables());
+            throw new PandaRuntimeException("Invalid variable index: " + index + "; Amount of localMemory: " + getMemorySize());
         }
     }
 
@@ -56,12 +56,12 @@ public synchronized <R> R set(int pointer, @Nullable R value) {
     }
 
     @Override
-    public int getAmountOfVariables() {
+    public int getMemorySize() {
         return localMemory.length;
     }
 
     @Override
-    public T getScope() {
+    public T getFramedScope() {
         return frame;
     }
 

panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcess.java

@@ -39,7 +39,7 @@ public PandaProcess(Application application, FramedScope mainScope, String... pa
     @Override
     @SuppressWarnings("unchecked")
     public @Nullable Object execute() {
-        ProcessStack stack = new PandaProcessStack(this, PandaProcessStackConstants.DEFAULT_STACK_SIZE);
+        ProcessStack stack = new PandaProcessStack(this, PandaRuntimeConstants.DEFAULT_STACK_SIZE);
 
         try {
             Frame instance = mainScope.revive(null, null);

panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcessStack.java

@@ -31,8 +31,6 @@
 import org.panda_lang.utilities.commons.collection.IStack;
 import org.panda_lang.utilities.commons.function.ThrowingSupplier;
 
-import java.util.function.Supplier;
-
 public class PandaProcessStack implements ProcessStack {
 
     private final Process process;
@@ -46,7 +44,7 @@ public PandaProcessStack(Process process, int stackCapacity) {
 
     @Override
     public @Nullable Result<?> call(Object instance, Frame frame) throws Exception {
-        return call(instance, frame, () -> call(frame, frame.getScope()));
+        return call(instance, frame, () -> call(frame, frame.getFramedScope()));
     }
 
     @Override
@@ -85,7 +83,7 @@ public PandaProcessStack(Process process, int stackCapacity) {
         if (statement instanceof Executable) {
             if (statement instanceof Controller) {
                 Controller controller = (Controller) statement;
-                return new Result<>(controller.getStatus(), controller.execute(this, instance));
+                return new Result<>(controller.getStatusCode(), controller.execute(this, instance));
             }
 
             ((Executable) statement).execute(this, instance);

panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaProcessStackConstants.java → panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaRuntimeConstants.java

@@ -16,8 +16,14 @@
 
 package org.panda_lang.framework.language.runtime;
 
-public final class PandaProcessStackConstants {
+/**
+ * Constants related to the runtime
+ */
+public final class PandaRuntimeConstants {
 
+    /**
+     * Default size of stack
+     */
     public static final int DEFAULT_STACK_SIZE = 1024;
 
 }

panda-framework/src/main/java/org/panda_lang/framework/language/runtime/PandaRuntimeException.java

@@ -20,9 +20,6 @@
 
 public class PandaRuntimeException extends PandaFrameworkException {
 
-    public PandaRuntimeException() {
-    }
-
     public PandaRuntimeException(String message) {
         super(message);
     }
@@ -31,8 +28,4 @@ public PandaRuntimeException(String message, Throwable cause) {
         super(message, cause);
     }
 
-    public PandaRuntimeException(Throwable cause) {
-        super(cause);
-    }
-
 }