Update API documentation

src/examples/java/coneforest.psylla.examples/module-info.java

@@ -1,3 +1,8 @@
+/**
+*	The Psylla example code.
+*
+*	@author Anton Shvetz ‹shvetz.anton@gmail.com›
+*/
 module coneforest.psylla.examples
 {
 	exports coneforest.psylla.examples;

src/main/java/coneforest.psylla.tools/module-info.java

@@ -2,6 +2,7 @@
 *	The Psylla language tools.
 *
 *	@author Anton Shvetz ‹shvetz.anton@gmail.com›
+*	@provides java.util.spi.ToolProvider
 */
 module coneforest.psylla.tools
 {

src/main/java/coneforest.psylla/coneforest/psylla/NamespacePool.java

@@ -12,6 +12,7 @@ public class NamespacePool
 	*	Allocates (if absent) and returns the {@code namespace} object with the given prefix.
 	*
 	*	@param prefix the prefix.
+	*	@return the {@code namespace} object.
 	*/
 	public PsyNamespace get(final String prefix)
 	{

src/main/java/coneforest.psylla/coneforest/psylla/OperatorType.java

@@ -6,7 +6,6 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-//@Target({/*ElementType.TYPE, */ElementType.TYPE_USE})
 @Documented
 @Target(ElementType.FIELD)
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/coneforest.psylla/coneforest/psylla/Psylla.java

@@ -227,19 +227,16 @@ private static void showVersion()
 
 	private static void showConfig(final List<String> patterns)
 	{
-		final Set<String> propertyNames=Config.stringPropertyNames();
-
+		final var propertyNames=Config.stringPropertyNames();
 		for(final String pattern: patterns)
-		{
 			propertyNames.stream()
 					.sorted()
 					.filter(name->Globs.matches(pattern, name))
 					.forEach(name->System.out.println(name+"=\'"+Config.getProperty(name)+"\'"));
-		}
 		System.exit(0);
 	}
 
-	private static class PsyllaConfig
+	public static class PsyllaConfig
 	{
 		private void setScriptReader(final Reader scriptReader)
 		{

src/main/java/coneforest.psylla/coneforest/psylla/Version.java

@@ -1,9 +1,9 @@
 package coneforest.psylla;
 
 /**
-*	A class holding versioning information.
+*	Versioning information.
 */
-public class Version
+public interface Version
 {
 	/**
 	*	Returns the version string.

src/main/java/coneforest.psylla/coneforest/psylla/core/PsyArray.java

@@ -48,12 +48,12 @@ public PsyArray psyClone()
 	}
 
 	@Override
-	public PsyObject get(final int indexValue)
+	public PsyObject get(final int index)
 		throws PsyRangeCheckException
 	{
 		try
 		{
-			return array.get(indexValue<0? indexValue+length(): indexValue);
+			return array.get(index<0? index+length(): index);
 		}
 		catch(final IndexOutOfBoundsException ex)
 		{
@@ -187,14 +187,29 @@ public void psySetLength(final PsyInteger oLength)
 		}
 	}
 
+	/**
+	*	Sorts this list according to the order induced by the specified comparator. The sort is
+	*	stable: this method must not reorder equal elements.
+	*
+	*	@param oComparator the {@code proc} comparator used to compare array elements.
+	*	@param oContext the execution context.
+	*/
 	public void psySort(final PsyProc oComparator, final PsyContext oContext)
 	{
-		Collections.sort(array, oComparator.asComparator(oContext));
+		array.sort(oComparator.asComparator(oContext));
 	}
 
+	/**
+	*	Searches this array for the specified value using the binary search algorithm. The array
+	*	must be sorted into ascending order according to the specified comparator. TODO
+	*
+	*	@param o the value to be searched for.
+	*	@param oComparator the comparator by which the array is ordered.
+	*	@param oContext the execution context.
+	*	@return TODO
+	*/
 	public PsyInteger psyBinarySearch(final PsyObject o, final PsyProc oComparator, final PsyContext oContext)
 	{
-		final var opstack=oContext.operandStack();
 		return PsyInteger.of(Collections.<PsyObject>binarySearch(array, o,
 				oComparator.asComparator(oContext)));
 	}

src/main/java/coneforest.psylla/coneforest/psylla/core/PsyBitwise.java

@@ -21,6 +21,7 @@ public interface PsyBitwise<T extends PsyBitwise>
 	*	@param oBit the index of bit to clear.
 	*	@return a {@code bitwise} whose value is equivalent to this value with
 	*	the designated bit cleared.
+	*	@throws PsyRangeCheckException if the index is out of range.
 	*/
 	public PsyBitwise psyClearBit(final PsyInteger oBit)
 		throws PsyRangeCheckException;
@@ -32,6 +33,7 @@ public PsyBitwise psyClearBit(final PsyInteger oBit)
 	*	@param oBit the index of bit to flip.
 	*	@return a {@code bitwise} whose value is equivalent to this value with
 	*	the designated bit flipped.
+	*	@throws PsyRangeCheckException if the index is out of range.
 	*/
 	public PsyBitwise psyFlipBit(final PsyInteger oBit)
 		throws PsyRangeCheckException;
@@ -43,6 +45,7 @@ public PsyBitwise psyFlipBit(final PsyInteger oBit)
 	*	@param oBit the index of bit to set.
 	*	@return a {@code bitwise} whose value is equivalent to this value with
 	*	the designated bit set.
+	*	@throws PsyRangeCheckException if the index is out of range.
 	*/
 	public PsyBitwise psySetBit(final PsyInteger oBit)
 		throws PsyRangeCheckException;
@@ -52,6 +55,7 @@ public PsyBitwise psySetBit(final PsyInteger oBit)
 	*
 	*	@param oBit the index of bit to test.
 	*	@return a {@code boolean} indicating if the designated bit set.
+	*	@throws PsyRangeCheckException if the index is out of range.
 	*/
 	public PsyBoolean psyTestBit(final PsyInteger oBit)
 		throws PsyRangeCheckException;

src/main/java/coneforest.psylla/coneforest/psylla/core/PsyContext.java

@@ -90,6 +90,11 @@ public void fork()
 	*/
 	public NamespacePool namespacePool();
 
+	/**
+	*	Returns the size of the execution stack.
+	*
+	*	@return the size of the execution stack.
+	*/
 	public int execLevel();
 
 	/**

src/main/java/coneforest.psylla/coneforest/psylla/core/PsyFormalArray.java

@@ -42,10 +42,18 @@ default public PsyFormalArray<T> psyReverse()
 	@Override
 	default public PsyBoolean psyKnown(final PsyInteger oIndex)
 	{
+		// TODO: index<0
 		long index=oIndex.longValue();
 		return PsyBoolean.of(index>=0 && index<length());
 	}
 
+	/**
+	*	Returns the element at the specified position in this array.
+	*
+	*	@param index the index of the element.
+	*	@return the element at the specified position in this list.
+	*	@throws PsyRangeCheckException if the index is out of range.
+	*/
 	public T get(final int index)
 		throws PsyRangeCheckException;
 
@@ -173,6 +181,12 @@ default public void psyDelete(final PsyInteger oIndex)
 		delete(oIndex.intValue());
 	}
 
+	/**
+	*	Removes the element at the specified position in this array.
+	*
+	*	@param index the index of the element to be removed.
+	*	@throws PsyRangeCheckException if the index is out of range.
+	*/
 	public void delete(int index)
 		throws PsyRangeCheckException;
 

src/main/java/coneforest.psylla/module-info.java

@@ -2,6 +2,7 @@
 *	The Psylla language interpreter and core.
 *
 *	@author Anton Shvetz ‹shvetz.anton@gmail.com›
+*	@provides javax.script.ScriptEngineFactory
 */
 module coneforest.psylla
 {

src/main/jj/coneforest.psylla/coneforest/psylla/Parser.jj

@@ -1,11 +1,26 @@
+options
+{
+	JDK_VERSION="17";
+	// BUILD_TOKEN_MANAGER=false;
+}
+
 PARSER_BEGIN(Parser)
 
 package coneforest.psylla;
 
 import coneforest.psylla.core.PsyReader;
 
+/**
+*	The Psylla language parser.
+*/
+@SuppressWarnings("javadoc")
 public class Parser
 {
+	/**
+	*	Constructs a new parser over given {@code reader} object.
+	*
+	*	@param oReader the {@code reader} object.
+	*/
 	public Parser(final PsyReader oReader)
 	{
 		this(oReader.reader());