docs: add some scaladoc

Author: kelvin-olaiya

src/main/scala/io/github/kelvindev15/prolog/core/Constant.scala

@@ -3,35 +3,62 @@ package io.github.kelvindev15.prolog.core
 import io.github.kelvindev15.prolog.core.Struct.quoteIfFunctorIsMalformed
 import io.github.kelvindev15.prolog.utils.TermVisitor
 
+/** A Prolog Constant, either numeric or an atom */
 trait Constant extends Term:
+  /** The value of the constant. */
   val value: Any
+  
   override def variables: Seq[Variable] = Seq()
+  
   override def isGround: Boolean = true
+  
   override def accept[T](visitor: TermVisitor[T]): T = visitor.visit(this)
+  
   override def asTerm: Term = this
 
 object Constant:
+  /** Returns a Prolog [[Constant]].
+   * 
+   * @param value the value of the constant.
+   * @throws IllegalArgumentException if the value cannot be used for an [[Atom]] or a [[Numeric]].
+   */
   def apply(value: Any): Constant = value match
     case n: (Int | Double) => Numeric(n)
     case s: String => Atom(s)
     case _ => throw IllegalArgumentException("Cannot create a constant with the provided argument")
+  
+  /** A Prolog atom. */
   trait Atom extends Constant with Struct:
     override val value: String
+    
+    /** The unquoted value of the atom. */
     val unquotedValue: String
+    
     override val arity: Int = 0
+    
     override val arguments: Seq[Term] = Seq()
+    
     override val functor: Atom = this
 
   object Atom:
     private def removeQuotes(value: String) = value.replaceAll("^'+|'+$", "")
+
+    /** Returns an instance of [[Atom]].
+     * 
+     * @param value the value of the atom.
+     */
     def apply(value: String): Atom = AtomImpl(removeQuotes(value))
+    
     private case class AtomImpl(private val _value: String) extends Atom:
       override val value: String = quoteIfFunctorIsMalformed(_value)
       override val unquotedValue: String = _value
 
+  /** A Prolog numeric constant. */
   trait Numeric extends Constant:
     override val value: AnyVal
 
   object Numeric:
+    /** Returns an instance of [[Numeric]] */
     def apply(value: AnyVal): Numeric = NumericImpl(value)
+    
     private case class NumericImpl(value: AnyVal) extends Numeric

src/main/scala/io/github/kelvindev15/prolog/core/Goals.scala

@@ -6,24 +6,63 @@ import io.github.kelvindev15.prolog.core.RecursiveStruct.BinaryRecursiveStruct
 import io.github.kelvindev15.prolog.utils.TermVisitor
 
 object Goals:
+  /** Represents a conjunction of goals. */
   trait Conjunction extends BinaryRecursiveStruct:
     override val functor: Constant.Atom = Functors.GOAL_CONJUNCTION
     override def accept[T](visitor: TermVisitor[T]): T = visitor.visit(this)
 
   object Conjunction:
+    /** Returns a [[Conjunction]] if more to arguments are provided, 
+     * otherwise return the provided term.
+     * 
+     * @param args the arguments to put in conjunction.
+     * @throws IllegalArgumentException if no arguments is provided.            
+     */
     def wrapIfNecessary(args: Term*): Term = BinaryRecursiveStruct.wrapIfNecessary(Conjunction.apply)(args*)
+
+    /** Returns an instance of [[Conjunction]].
+     * 
+     * @param args the arguments to put in conjunction.
+     * @throws IllegalArgumentException if less of two arguments are provided.            
+     */
     def apply(args: Term*): Conjunction = BinaryRecursiveStruct.fold(ConjunctionImpl.apply)(args*)
+
+    /** Deconstructs the Conjuction in its arguments.
+     * 
+     * @param conjunction the conjunction to deconstruct.
+     */
     def unapply(conjunction: Conjunction): Option[(Term, Term)] = Option((conjunction.first, conjunction.second))
+    
     private case class ConjunctionImpl(left: Term, right: Term) extends Conjunction
 
+  /** Represents a disjunction of goals. */
   trait Disjunction extends BinaryRecursiveStruct:
     override val functor: Constant.Atom = Functors.GOAL_DISJUNCTION
     override def accept[T](visitor: TermVisitor[T]): T = visitor.visit(this)
 
   object Disjunction:
+    /** Returns a [[Disjunction]] if more to arguments are provided, 
+     * otherwise return the provided term.
+     *
+     * @param args the arguments to put in disjuction.
+     * @throws IllegalArgumentException if no arguments is provided.            
+     */
     def wrapIfNecessary(args: Term*): Term = BinaryRecursiveStruct.wrapIfNecessary(Disjunction.apply)(args*)
+
+    /** Returns an instance of [[Conjunction]].
+     *
+     * @param args the arguments to put in disjunction.
+     * @throws IllegalArgumentException if less of two arguments are provided.            
+     */
+
     def apply(args: Term*): Disjunction = BinaryRecursiveStruct.fold(DisjunctionImpl.apply)(args*)
+
+    /** Deconstructs the Disjunction in its arguments.
+     *
+     * @param disjunction the disjunction to deconstruct.
+     */
     def unapply(disjunction: Disjunction): Option[(Term, Term)] = Option((disjunction.first, disjunction.second))
+    
     private case class DisjunctionImpl(left: Term, right: Term) extends Disjunction
 
 

src/main/scala/io/github/kelvindev15/prolog/core/Prolog.scala

@@ -6,7 +6,10 @@ import scala.util.matching.Regex
 
 object Prolog:
   object Syntax:
+    /** Prolog's atom syntax regex */
     val AtomRegex: Regex = "^[a-z][a-zA-Z_0-9]*$".r
+    
+    /** Prolog's variable syntax regex */
     val VariableRegex: Regex = "[A-Z_][a-zA-Z_0-9]*".r
 
   object Functors:

src/main/scala/io/github/kelvindev15/prolog/core/PrologList.scala

@@ -3,33 +3,53 @@ package io.github.kelvindev15.prolog.core
 import io.github.kelvindev15.prolog.core.Constant.Atom
 import io.github.kelvindev15.prolog.core.Prolog.Functors
 
+/** A Prolog list */
 trait PrologList extends RecursiveStruct:
+  /** The number of elements in the list. */
   val size: Int
 
 object PrologList:
   extension (listTerminator: (PrologList | Variable))
+    /** Returns all arguments of the list in a sequence. */
     def linearizedArguments: Seq[Term] = listTerminator match
       case l: PrologList => l.linearizedArguments
       case v: Variable => Seq(v)
 
   given Conversion[(PrologList | Variable), Term] = _.asInstanceOf[Term]
+  
+  /** Returns an instance of [[PrologList]].
+   * 
+   * @param elements the elements to include in the list.
+   */
+  def apply(elements: Term*): PrologList = elements.size match
+    case 0 => Nil
+    case 1 => Cons(elements.head, Nil)
+    case _ => Cons(elements.head, apply(elements.tail *))
 
+  /** A Prolog list, comprises a head and a tail. */
   trait Cons extends PrologList:
+    /** The head of the list */
     val head: Term
+
+    /** The tail of the list. */
     val tail: (PrologList | Variable)
 
     override def linearizedArguments: Seq[Term] = Seq(head) ++ tail.linearizedArguments
+
     override val arity: Int = 2
+
     override val arguments: Seq[Term] = Seq(head, tail)
+
     override val size: Int = linearizedArguments.size
-    override val functor: Constant.Atom = Functors.CONS
 
-  def apply(elements: Term*): PrologList = elements.size match
-    case 0 => Nil
-    case 1 => Cons(elements.head, Nil)
-    case _ => Cons(elements.head, apply(elements.tail *))
+    override val functor: Constant.Atom = Functors.CONS
 
   object Cons:
+    /** Returns an instance of [[Cons]].
+     * 
+     * @param head the head of the list.
+     * @param tail the tail of the list.
+     */
     def apply(head: Term, tail: (PrologList | Variable)): PrologList = ConsImpl(head, tail)
 
   object Nil extends PrologList:
@@ -38,7 +58,6 @@ object PrologList:
     override val arguments: Seq[Term] = Seq()
     override val size: Int = 0
     override def asTerm: Term = Functors.EMPTY_LIST
-
     override val functor: Constant.Atom = Functors.EMPTY_LIST
 
   private case class ConsImpl(head: Term, tail: (PrologList | Variable)) extends Cons:

src/main/scala/io/github/kelvindev15/prolog/core/RecursiveStruct.scala

@@ -2,33 +2,61 @@ package io.github.kelvindev15.prolog.core
 
 import io.github.kelvindev15.prolog.utils.BinaryToFlatVisitor
 
+/** A Prolog [[Struct]] that is also recursive. */
 trait RecursiveStruct extends Struct:
+  /** All arguments of the struct linearized in a list. */
   def linearizedArguments: Seq[Term]
+  
   override def foreach(action: Term => Unit): Unit = linearizedArguments.foreach(action)
 
 object RecursiveStruct:
+  /** A  [[RecursiveStruct]] that is also binary. */
   trait BinaryRecursiveStruct extends RecursiveStruct:
     final override val arity: Int = 2
+    /** The first argument of the struct. */
     def first: Term = left
+    
+    /** The second argument of the struct. */
     def second: Term = right
+    
+    /** Alias of [[first]]. */
     def left: Term
+    
+    /** Alias of [[second]]. */
     def right: Term
+    
     final override val arguments: Seq[Term] = Seq(left, right)
+    
     override def linearizedArguments: Seq[Term] = accept(BinaryToFlatVisitor())
+    
     final override def asTerm: Term = Struct(functor, left.asTerm, right.asTerm)
 
   object BinaryRecursiveStruct:
-    def wrapIfNecessary(struct: Seq[Term] => BinaryRecursiveStruct)(args: Term*): Term = args.size match
+    /** Binarize a list of [[Term]]s using a strategy.
+     * 
+     * @param strategy the binarization strategy.
+     * @param args the arguments to binarize.
+     *             
+     * @throws IllegalArgumentException if the are no [[args]].
+     */
+    def wrapIfNecessary(strategy: Seq[Term] => BinaryRecursiveStruct)(args: Term*): Term = args.size match
       case 0 => throw IllegalArgumentException("Cannot create a goal from an empty sequence")
       case 1 => args.head
-      case _ => struct(args)
+      case _ => strategy(args)
 
+    /** A destructuring object for [[BinaryRecursiveStruct]]s. */
     object Tuple:
       def unapply(tuple: BinaryRecursiveStruct): Option[(Term, Term)] =
         Option((tuple.left, tuple.right))
 
-    def fold[T <: BinaryRecursiveStruct](struct: (Term, Term) => T)(args: Term*): T = args.size match
+    /** Folds a sequence of arguments into a binarized struct using a strategy.
+     * 
+     * @param strategy the strategy for binarization.
+     * @param args the sequence of terms.
+     * @tparam T the type of [[BinaryRecursiveStruct]].
+     */
+    def fold[T <: BinaryRecursiveStruct](strategy: (Term, Term) => T)(args: Term*): T = args.size match
       case n if n < 2 => throw IllegalArgumentException("There must be at least two arguments")
-      case 2 => struct(args.head, args.tail.head)
-      case _ => struct(args.head, fold(struct)(args.tail *))
+      case 2 => strategy(args.head, args.tail.head)
+      case _ => strategy(args.head, fold(strategy)(args.tail *))