GH-392 Document parser pipeline design classes

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/parser/pipeline/HandleResult.java

@@ -21,6 +21,11 @@
 
 import java.util.Optional;
 
+/**
+ * Wrapper for pipeline handle result
+ *
+ * @param <T> type of the result parser
+ */
 public interface HandleResult<T extends Parser> {
 
     /**

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/parser/pipeline/Handler.java

@@ -16,17 +16,28 @@
 
 package org.panda_lang.framework.design.interpreter.parser.pipeline;
 
+import org.jetbrains.annotations.Nullable;
 import org.panda_lang.framework.design.interpreter.parser.Context;
 import org.panda_lang.framework.design.interpreter.token.Snippet;
 
+/**
+ * Checkout the requested source
+ */
 public interface Handler {
 
     /**
-     * Handle source
+     * Handle source, possible results:
+     *
+     * <ul>
+     *     <li>InterpreterFailure - that will be stored and printed if there is no matching handler</li>
+     *     <li>Exception - that will interrupt pipeline</li>
+     *     <li>boolean - true/false if matched or not</li>
+     *     <li>other/null - illegal return value</li>
+     * </ul>
      *
      * @param source source
-     * @return returns true if parsers fits to source
+     * @return the result object
      */
-    Object handle(Context context, Channel channel, Snippet source);
+    @Nullable Object handle(Context context, Channel channel, Snippet source);
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/parser/pipeline/PipelineComponent.java

@@ -23,6 +23,11 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Component that represents a pipeline
+ *
+ * @param <P> pipeline parser type
+ */
 public class PipelineComponent<P extends Parser> extends Component<P> {
 
     private static final Map<String, PipelineComponent<? extends Parser>> COMPONENTS = new HashMap<>();

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/parser/pipeline/PipelineComponents.java

@@ -20,8 +20,16 @@
 import java.util.Collection;
 import java.util.stream.Collectors;
 
+/**
+ * Represents collection of pipeline components
+ */
 public interface PipelineComponents {
 
+    /**
+     * Collect pipeline components
+     *
+     * @return collection of pipeline components
+     */
     default Collection<PipelineComponent<?>> collectPipelineComponents() {
         return Arrays.stream(this.getClass().getFields())
                 .filter(field -> PipelineComponent.class.isAssignableFrom(field.getType()))

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/parser/pipeline/PipelinePath.java

@@ -20,16 +20,49 @@
 
 import java.util.Collection;
 
+/**
+ * Container of pipelines
+ */
 public interface PipelinePath {
 
+    /**
+     * Create a new pipeline based on the given component
+     *
+     * @param component the component to use
+     * @param <P> type of parsers represented by pipeline
+     * @return a new pipeline
+     */
     <P extends Parser> Pipeline<P> createPipeline(PipelineComponent<P> component);
 
+    /**
+     * Check if path contains the given pipeline
+     *
+     * @param component the identifier of pipeline to search for
+     * @return true if pipeline exists in the path, otherwise false
+     */
     boolean hasPipeline(PipelineComponent<?> component);
 
+    /**
+     * Get pipeline using the given component
+     *
+     * @param component the component to search for
+     * @param <P> the type of represented parsers by requested pipeline
+     * @return the found pipeline
+     */
     <P extends Parser> Pipeline<P> getPipeline(PipelineComponent<P> component);
 
+    /**
+     * Get sum of handle times stored by pipelines in the path
+     *
+     * @return a sum of handle times
+     */
     long getTotalHandleTime();
 
+    /**
+     * Collect names of pipelines
+     *
+     * @return the collection of pipelines names
+     */
     Collection<String> names();
 
 }

panda-framework/src/main/java/org/panda_lang/framework/design/interpreter/parser/pipeline/Pipelines.java

@@ -18,6 +18,9 @@
 
 import org.panda_lang.framework.design.interpreter.parser.ContextParser;
 
+/**
+ * Default pipelines used by the framework
+ */
 public final class Pipelines implements PipelineComponents {
 
     /**