docs: add code comments

Author: thomasleplus

src/main/java/org/leplus/sql/ConstantListener.java

@@ -6,6 +6,11 @@
 import org.leplus.antlr4.PLSQLBaseListener;
 import org.leplus.antlr4.PLSQLParser.ConstantContext;
 
+/**
+ * ANTLR listener that collects the literal constants of a PL/SQL parse tree.
+ * {@code NULL} literals are skipped, since they denote absence rather than a
+ * value.
+ */
 public class ConstantListener extends PLSQLBaseListener {
 
   private static final String NULL = "NULL";
@@ -27,6 +32,9 @@ public void enterConstant(final ConstantContext ctx) {
     addResult(ctx);
   }
 
+  /**
+   * @return an unmodifiable view of the constants collected so far.
+   */
   public List<Result> getResults() {
     return Collections.unmodifiableList(results);
   }

src/main/java/org/leplus/sql/ExceptionErrorListener.java

@@ -4,6 +4,11 @@
 import org.antlr.v4.runtime.RecognitionException;
 import org.antlr.v4.runtime.Recognizer;
 
+/**
+ * An ANTLR error listener that makes parsing fail fast: instead of ANTLR's
+ * default "recover and continue", it rethrows the recognition exception on the
+ * first syntax error.
+ */
 public class ExceptionErrorListener extends BaseErrorListener {
 
   public ExceptionErrorListener() {

src/main/java/org/leplus/sql/Inspector.java

@@ -7,12 +7,21 @@
 import org.leplus.antlr4.PLSQLLexer;
 import org.leplus.antlr4.PLSQLParser;
 
+/** Inspects SQL statements for literal constants, using an ANTLR4 PL/SQL grammar. */
 public class Inspector {
 
   public Inspector() {
     super();
   }
 
+  /**
+   * Parses a SQL statement and returns the literal constants it contains, in
+   * source order. Parsing fails fast: the first syntax error is rethrown (see
+   * {@link ExceptionErrorListener}).
+   *
+   * @param sqlStatement the SQL text to inspect.
+   * @return the constants found.
+   */
   public List<Result> findConstants(final String sqlStatement) {
     final PLSQLLexer lexer = new PLSQLLexer(CharStreams.fromString(sqlStatement));
     final CommonTokenStream tokens = new CommonTokenStream(lexer);

src/main/java/org/leplus/sql/Result.java

@@ -2,6 +2,10 @@
 
 import java.io.Serializable;
 
+/**
+ * A literal constant found in a SQL statement: its text value and its position.
+ * Ordered by line, then column, then value.
+ */
 public class Result implements Serializable, Comparable<Result> {
 
   private static final long serialVersionUID = 2722874450358413200L;