Update API documentation

src/main/java/coneforest.psylla/coneforest/psylla/ContextAction.java

@@ -3,12 +3,28 @@
 import coneforest.psylla.core.*;
 import java.util.Optional;
 
+/**
+*	An action on the execution context.
+*/
 @FunctionalInterface
 public interface ContextAction
 {
+	/**
+	*	Performs this action on the specified execution context.
+	*
+	*	@param oContext the execution context.
+	*	@throws PsyErrorException when an error occurs.
+	*/
 	public void perform(final PsyContext oContext)
 		throws PsyErrorException;
 
+	/**
+	*	Returns the context action created from the consumer.
+	*
+	*	@param <T> the type of the input to the consumer.
+	*	@param consumer the consumer.
+	*	@return the context action created.
+	*/
 	public static <T extends PsyObject> ContextAction ofConsumer(final Consumer<T> consumer)
 	{
 		return oContext->
@@ -18,6 +34,12 @@ public static <T extends PsyObject> ContextAction ofConsumer(final Consumer<T> c
 			};
 	}
 
+	/**
+	*	Returns the context action created from the supplier.
+	*
+	*	@param supplier the supplier.
+	*	@return the context action created.
+	*/
 	public static ContextAction ofSupplier(final Supplier supplier)
 	{
 		return oContext->oContext.operandStack().push(supplier.get());

src/main/java/coneforest.psylla/coneforest/psylla/Interpreter.java

@@ -147,11 +147,6 @@ public PsyFormalDict currentDict()
 		return dstack.peek();
 	}
 
-	/**
-	*	Returns system dictionary.
-	*
-	*	@return the system dictionary.
-	*/
 	@Override
 	public PsyFormalDict systemDict()
 	{

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

@@ -3,8 +3,16 @@
 import coneforest.psylla.core.*;
 import java.util.HashMap;
 
+/**
+*	A namespace pool.
+*/
 public class NamespacePool
 {
+	/**
+	*	Allocates (if absent) and returns the {@code namespace} object with the given prefix.
+	*
+	*	@param prefix the prefix.
+	*/
 	public PsyNamespace get(final String prefix)
 	{
 		if(!pool.containsKey(prefix))

src/main/java/coneforest.psylla/coneforest/psylla/OperandStack.java

@@ -19,6 +19,13 @@ public void clearBackup()
 		backupSize=0;
 	}
 
+	/**
+	*	Ensures that the operand stack is at least the given size.
+	*
+	*	@param size the given size.
+	*	@throws PsyStackUnderflowException when the operand stack’s size less than the given size.
+	*	@throws PsyRangeCheckException when given size is negative.
+	*/
 	public void ensureSize(final int size)
 		throws PsyRangeCheckException, PsyStackUnderflowException
 	{
@@ -49,6 +56,12 @@ public void rollback()
 		backupSize=0;
 	}
 
+	/**
+	*	Returns the position of the topmost {@code mark} object on the operand stack.
+	*
+	*	@return the position of the topmost {@code mark} object on the operand stack.
+	*	@throws PsyUnmatchedMarkException when there is no {@code mark} object on the operand stack.
+	*/
 	public int findMarkPosition()
 		throws PsyUnmatchedMarkException
 	{

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

@@ -14,26 +14,26 @@ public interface PsyAdditive<T extends PsyAdditive>
 {
 
 	/**
-	*	Returns an {@code additive} representing the result of arithmetic negation of this object.
+	*	Returns the {@code additive} result of arithmetic negation of this object.
 	*
-	*	@return a negation.
+	*	@return the {@code additive} result of arithmetic negation.
 	*/
 	public T psyNeg();
 
 	/**
-	*	Returns an {@code additive} representing the result of arithmetic addition of given object
-	*	to this object.
+	*	Returns the {@code additive} result of arithmetic addition of specified object to this
+	*	object.
 	*
-	*	@param oAdditive given object.
-	*	@return a sum.
+	*	@param oAdditive the specified object.
+	*	@return the sum.
 	*/
 	public T psyAdd(final T oAdditive);
 
 	/**
-	*	Returns an {@code additive} representing the result of arithmetic subtraction of given
-	*	object from this object.
+	*	Returns the {@code additive} result of arithmetic subtraction of specified object from this
+	*	object.
 	*
-	*	@param oAdditive given object.
+	*	@param oAdditive the specified object.
 	*	@return a difference.
 	*/
 	public T psySub(final T oAdditive);

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

@@ -3,7 +3,7 @@
 import coneforest.psylla.*;
 
 /**
-*	The representation of {@code complex}.
+*	The representation of {@code complex}, a complex number.
 */
 @Type("complex")
 public final class PsyComplex
@@ -269,9 +269,15 @@ public static PsyComplex psyFromPolar(final double abs, final double arg)
 		return new PsyComplex(abs*Math.cos(arg), abs*Math.sin(arg));
 	}
 
-	public static final PsyComplex
-		I=new PsyComplex(0.D, 1.D),
-		MINUS_I=new PsyComplex(0.D, -1.D);
+	/**
+	*	Imaginary unit.
+	*/
+	public static final PsyComplex I=new PsyComplex(0.D, 1.D);
+
+	/**
+	*	Munus imaginary unit.
+	*/
+	public static final PsyComplex MINUS_I=new PsyComplex(0.D, -1.D);
 
 	private final double re, im;
 

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

@@ -57,6 +57,11 @@ public void fork()
 	*/
 	public ExecutionStack executionStack();
 
+	/**
+	*	Returns the system dictionary.
+	*
+	*	@return the system dictionary.
+	*/
 	public PsyFormalDict systemDict();
 
 	/**
@@ -130,6 +135,11 @@ public void fork()
 	public void repl()
 		throws PsyErrorException;
 
+	/**
+	*	Sets the stopped flag to the specified value.
+	*
+	*	@param stopFlag the value of the stopped flag.
+	*/
 	public void setStopped(final boolean stopFlag);
 
 	public void handleExecutionStack(final int level);

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

@@ -29,111 +29,110 @@ public sealed interface PsyNumeric
 	public double imagValue();
 
 	/**
-	*	Returns a {@code numeric} absolute value of this object.
+	*	Returns the {@code numeric} absolute value of this object.
 	*
-	*	@return a {@code numeric} absolute value.
+	*	@return the {@code numeric} absolute value.
 	*/
 	public PsyRealNumeric psyAbs();
 
 
 	/**
-	*	Returns the signum of this object.
+	*	Returns the {@code numeric} signum of this object.
 	*
-	*	@return the {@code numeric} signum of this object.
+	*	@return the {@code numeric} signum.
 	*/
 	public PsyNumeric psySignum();
 
 	public PsyNumeric psyPow(final PsyNumeric oNumeric);
 
 	/**
-	*	Returns a {@code numeric} representing the exponent of this object.
+	*	Returns the {@code numeric} exponent of this object.
 	*
-	*	@return a {@code numeric} exponent.
+	*	@return the {@code numeric} exponent.
 	*/
 	public PsyNumeric psyExp();
 
 	/**
-	*	Returns a {@code numeric} representing the cosine of this object.
+	*	Returns the {@code numeric} cosine of this object.
 	*
-	*	@return a {@code numeric} cosine.
+	*	@return the {@code numeric} cosine.
 	*/
 	public PsyNumeric psyCos();
 
 	/**
-	*	Returns a {@code numeric} representing the sine of this object.
+	*	Returns the {@code numeric} sine of this object.
 	*
-	*	@return a {@code numeric} sine.
+	*	@return the {@code numeric} sine.
 	*/
 	public PsyNumeric psySin();
 
 	/**
-	*	Returns a {@code numeric} representing the tangent of this object.
+	*	Returns the {@code numeric} tangent of this object.
 	*
-	*	@return a {@code numeric} tangent.
+	*	@return the {@code numeric} tangent.
 	*/
 	public PsyNumeric psyTan();
 
 	/**
-	*	Returns a {@code numeric} representing the natural logarithm of this
-	*	object.
+	*	Returns the {@code numeric} natural logarithm of this object.
 	*
-	*	@return a {@code numeric} logarithm.
+	*	@return the {@code numeric} natural logarithm.
 	*/
 	public PsyNumeric psyLog();
 
 	/**
-	*	Returns a {@code numeric} representing the arc cosine of this object.
+	*	Returns the {@code numeric} arc cosine of this object.
 	*
-	*	@return a {@code numeric} arc cosine.
+	*	@return the {@code numeric} arc cosine.
 	*/
 	public PsyNumeric psyAcos();
 
 	/**
-	*	Returns a {@code numeric} representing the arc sine of this object.
+	*	Returns the {@code numeric} arc sine of this object.
 	*
-	*	@return a {@code numeric} arc sine.
+	*	@return the {@code numeric} arc sine.
 	*/
 	public PsyNumeric psyAsin();
 
 	/**
-	*	Returns a {@code numeric} representing the arc tangent of this object.
+	*	Returns the {@code numeric} arc tangent of this object.
 	*
-	*	@return a {@code numeric} arc tangent.
+	*	@return the {@code numeric} arc tangent.
 	*/
 	public PsyNumeric psyAtan();
 
 	/**
-	*	Returns a {@code numeric} representing the square root of this object.
+	*	Returns the {@code numeric} square root of this object.
 	*
-	*	@return a {@code numeric} square root of this number.
+	*	@return the {@code numeric} square root.
 	*/
 	public PsyNumeric psySqrt();
 
 	/**
-	*	Returns a {@code numeric} representing the cubic root of this object.
+	*	Returns the {@code numeric} cubic root of this object.
 	*
-	*	@return a {@code numeric} cubic root of this number.
+	*	@return the {@code numeric} cubic root.
 	*/
 	public PsyNumeric psyCbrt();
 
 	/**
-	*	Returns a {@code numeric} representing the hyperbolic cosine of this object.
+	*	Returns the {@code numeric} hyperbolic cosine of this object.
 	*
-	*	@return a {@code numeric} hyperbolic cosine of this number.
+	*	@return the {@code numeric} hyperbolic cosine.
 	*/
 	public PsyNumeric psyCosh();
 
 	/**
-	*	Returns a {@code numeric} representing the hyperbolic sine of this object.
+	*	Returns the {@code numeric} hyperbolic sine of this object.
 	*
-	*	@return a {@code numeric} hyperbolic sine of this number.
+	*	@return the {@code numeric} hyperbolic sine.
 	*/
 	public PsyNumeric psySinh();
 
 	/**
-	*	Returns a {@code numeric} representing the hyperbolic tangent of this object.
+	*	Returns the {@code numeric} hyperbolic tangent of this object.
 	*
-	*	@return a {@code numeric} hyperbolic tangent of this number.
+	*	@return the {@code numeric} hyperbolic tangent.
 	*/
 	public PsyNumeric psyTanh();
 

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

@@ -102,6 +102,11 @@ default public PsyName psyToName()
 		return new PsyName(toSyntaxString());
 	}
 
+	/**
+	*	Returns the syntactic representation of this object.
+	*
+	*	@return the syntactic representation of this object.
+	*/
 	default public String toSyntaxString()
 	{
 		return '%'+typeName()+'%';

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

@@ -18,11 +18,22 @@ public class PsyReader
 		PsyReadable,
 		PsyResetable
 {
+
+	/**
+	*	Constructs a new {@code reader} object from the reader.
+	*
+	*	@param reader the reader.
+	*/
 	public PsyReader(final Reader reader)
 	{
 		this.reader=reader;
 	}
 
+	/**
+	*	Constructs a new {@code reader} object from the input stream.
+	*
+	*	@param is the input stream.
+	*/
 	public PsyReader(final InputStream is)
 	{
 		this(new InputStreamReader(is));