Uzupełnienie dokumentacji

Author: koder95

src/main/java/pl/koder95/interpreter/Expression.java

@@ -1,6 +1,17 @@
 package pl.koder95.interpreter;
 
+/**
+ * Interfejs dostarcza wyrażenie w formie ciągu znaków zwracany przez metodę {@code asString()}.
+ * Ma dwie dopuszczalne odmiany, które różnią się ze względu na funkcje i znaczenie w procesie interpretacji.
+ * <ol>
+ *     <li>{@link NonTerminalExpression} – wyrażenie nieterminalne, które stanowi podstawowy element budowania innych typów wyrażeń</li>
+ *     <li>{@link TerminalExpression} – wyrażenie terminalne, które można zinterpretować w ramach dostępnego kontekstu</li>
+ * </ol>
+ */
 public sealed interface Expression permits TerminalExpression, NonTerminalExpression {
 
+    /**
+     * @return wyrażenie w postaci ciągu znaków
+     */
     String asString();
 }

src/main/java/pl/koder95/interpreter/Interpreter.java

@@ -34,6 +34,9 @@ public interface Interpreter<C extends Context, R> {
      *
      * @param readable dane odczytywane przez tokenizer i zamieniane na postać terminalną
      * @return wynik interpretacji
+     * @throws IllegalStateException w przypadku niedostarczenia parsera lub
+     *                               w przypadku niedostarczenia tokenizera przez parser
+     * @throws SyntaxException w przypadku błędów składniowych w dostarczonych danych
      */
     default R interpret(Readable readable) {
         Tokenizer tokenizer = getTokenizer();

src/main/java/pl/koder95/interpreter/NonTerminalExpression.java

@@ -2,7 +2,18 @@
 
 import java.util.Objects;
 
+/**
+ * Wyrażenie nieterminalne to takie, któremu nie można przypisać żadnego znaczenia, ale jest podstawowym elementem,
+ * z którego zbudowane mogą być {@link TerminalExpression wyrażenia terminalne}. Jest to odpowiednik tokena lub symbolu.
+ * @param <T> typ obiektu, który może zostać skojarzony z wyrażeniem
+ */
 public non-sealed interface NonTerminalExpression<T> extends Expression {
+    /**
+     * Zwraca obiekt skojarzony z wyrażeniem, czyli taki, który stanowi wartość wyrażenia, jego reprezentację
+     * lub jego dookreślenie. Wykorzystywany jest podczas interpretowania
+     * przez {@link TerminalExpression wyrażenia terminalne}.
+     * @return obiekt skojarzony z wyrażeniem
+     */
     T getObject();
 
     @Override

src/main/java/pl/koder95/interpreter/Parser.java

@@ -13,6 +13,7 @@ public interface Parser<C extends Context, R> {
      * Buduje drzewo abstrakcyjnej syntaktyki.
      * @param tokens dane wejściowe poddane tokenizacji
      * @return wyrażenie terminalne najwyższego poziomu
+     * @throws SyntaxException w przypadku błędów składniowych w dostarczonych danych
      */
     TerminalExpression<C, R> buildAbstractSyntaxTree(Queue<NonTerminalExpression<?>> tokens);
 }

src/main/java/pl/koder95/interpreter/SyntaxException.java

@@ -5,17 +5,36 @@
  */
 public class SyntaxException extends IllegalArgumentException {
 
+    /**
+     * Tworzy ogólny wyjątek.
+     */
     public SyntaxException() {
     }
 
+    /**
+     * Tworzy wyjątek, który przekazuje wiadomość wyjaśniającą jego wyrzucenie.
+     *
+     * @param message wiadomość wyjaśniająca wyrzucenie wyjątku
+     */
     public SyntaxException(String message) {
         super(message);
     }
 
+    /**
+     * Tworzy wyjątek, który przekazuje wiadomość wyjaśniającą jego wyrzucenie oraz powód wyrzucenia.
+     *
+     * @param message wiadomość wyjaśniająca wyrzucenie wyjątku
+     * @param cause powód wyrzucenia wyjątku
+     */
     public SyntaxException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    /**
+     * Tworzy wyjątek, który przekazuje powód jego wyrzucenia.
+     *
+     * @param cause powód wyrzucenia wyjątku
+     */
     public SyntaxException(Throwable cause) {
         super(cause);
     }

src/main/java/pl/koder95/interpreter/TerminalExpression.java

@@ -1,5 +1,18 @@
 package pl.koder95.interpreter;
 
+/**
+ * Wyrażenie terminalne to takie, które można zinterpretować, dlatego interfejs dostarcza
+ * metodę zwracającą obiekt żądanego typu uzyskany w wyniku interpretacji.
+ * @param <C> typ kontekstu wykorzystywanego podczas interpretowania wyrażenia
+ * @param <R> typ obiektu zwracanego w wyniku interpretacji
+ */
 public non-sealed interface TerminalExpression<C extends Context, R> extends Expression {
+
+    /**
+     * Poddaje wyrażenie interpretacji, korzystając z podanego kontekstu.
+     * @param context kontekst wykorzystywany podczas interpretowania wyrażenia
+     * @return wynik interpretacji
+     * @throws SyntaxException błąd składniowy wewnątrz wyrażenia
+     */
     R interpret(C context);
 }

src/main/java/pl/koder95/interpreter/Tokenizer.java

@@ -41,6 +41,7 @@ protected final Scanner getScanner() {
      * Umieszcza w kolejce wszystkie możliwe do odczytania tokeny.
      * @param queue kolejka wyrażeń nieterminalnych (tokenów)
      * @return {@code queue}
+     * @throws SyntaxException w przypadku błędów składniowych w dostarczonych danych
      */
     public final Queue<NonTerminalExpression<?>> enqueue(Queue<NonTerminalExpression<?>> queue) {
         while (hasNext()) queue.add(next());
@@ -50,6 +51,7 @@ public final Queue<NonTerminalExpression<?>> enqueue(Queue<NonTerminalExpression
     /**
      * Tworzy nową kolejkę wyrażeń nieterminalnych (tokenów) i umieszcza w niej odczytane tokeny z wejścia.
      * @return nowa instancja kolejki {@link NonTerminalExpression wyrażeń nieterminalnych (tokenów)}
+     * @throws SyntaxException w przypadku błędów składniowych w dostarczonych danych
      */
     public Queue<NonTerminalExpression<?>> enqueue() {
         return enqueue(new LinkedBlockingQueue<>());
@@ -67,6 +69,7 @@ public boolean hasNext() {
      * Przetwarza dane wejściowe i zwraca je w postaci {@link NonTerminalExpression wyrażenia nieterminalnego},
      * czyli tokenu.
      * @return token typu {@link NonTerminalExpression}
+     * @throws SyntaxException w przypadku błędów składniowych w dostarczonych danych
      */
     public abstract NonTerminalExpression<?> next();
 }