docs: add some scaladoc

Author: kelvin-olaiya

src/main/scala/io/github/kelvindev15/prolog/PrologProgram.scala

@@ -3,18 +3,53 @@ package io.github.kelvindev15.prolog
 import io.github.kelvindev15.prolog.core.Term
 import io.github.kelvindev15.prolog.core.theory.Theory
 
+/** Represents an instance of a prolog program. */
 trait PrologProgram:
-  def staticTheory: Theory
-  def dynamicTheory: Theory
-  def goal: Option[Term]
+
+  /** The static [[Theory]] of the program. */
+  val staticTheory: Theory
+
+  /** The dynamic [[Theory]] of the program. */
+  val dynamicTheory: Theory
+
+  /** An [[Option]] that if filled with the goal set for the program. */
+  val goal: Option[Term]
+
+  /** Returns this program with the new provided goal.
+   *
+   * @param goal a [[Term]] representing the goal to be set for this program.
+   */
   def withGoal(goal: Term): PrologProgram
+
+  /** Returns this program with the new provided static theory.
+   *
+   * @param theory the static [[Theory]] to be set for this program.
+   * @return
+   */
   def setStaticTheory(theory: Theory): PrologProgram
+
+  /** Returns this program with the new provided dynamic theory
+   *
+   * @param theory the dynamic [[Theory]] to be set for this program.
+   * @return
+   */
   def setDynamicTheory(theory: Theory): PrologProgram
 
 object PrologProgram:
+
+  /** Returns an instance of a [[PrologProgram]].
+   *
+   * @param staticTheory the static [[Theory]] of the prolog program
+   * @param dynamicTheory the dynamic [[Theory]] of the prolog program
+   */
   def apply(staticTheory: Theory = Theory(), dynamicTheory: Theory = Theory()): PrologProgram =
     PrologProgramImpl(staticTheory, dynamicTheory, None)
-    
+
+  /**
+   *
+   * @return an instance of a [[PrologProgram]] whose static and dynamic [[Theory]] are empty and
+   *         with no goal.
+   */
   def emptyTheory: PrologProgram = PrologProgramImpl(Theory.empty, Theory.empty, None)  
 
   private case class PrologProgramImpl(

src/main/scala/io/github/kelvindev15/prolog/dsl/DSLConversions.scala

@@ -4,7 +4,7 @@ import io.github.kelvindev15.prolog.core.Constant.Atom
 import io.github.kelvindev15.prolog.core.Struct.Fact
 import io.github.kelvindev15.prolog.core.{Constant, PrologList, Struct, Term}
 
-trait DSLConversions:
+protected trait DSLConversions:
   dsl: PrologDSL =>
   given Conversion[String, Atom] = Atom(_)
   given Conversion[AnyVal, Constant] = {

src/main/scala/io/github/kelvindev15/prolog/dsl/DSLExtensions.scala

@@ -6,7 +6,7 @@ import io.github.kelvindev15.prolog.core.{Goals, Struct, Term}
 
 import scala.annotation.targetName
 
-trait DSLExtensions:
+protected trait DSLExtensions:
   dsl: PrologDSL =>
   extension (atom: Atom)
     def apply(terms: Term*): Struct = Struct(atom, terms *)

src/main/scala/io/github/kelvindev15/prolog/dsl/DSLPrologBuiltins.scala

@@ -7,61 +7,187 @@ import io.github.kelvindev15.prolog.core.{Constant, Prolog, Struct, Term}
 
 import scala.annotation.targetName
 
-enum AssociativitySpec extends Atom:
+protected enum AssociativitySpec extends Atom:
   case fx, fy, xf, xfx, xfy, yfx, yfy
   override val value: String = toString
   override val unquotedValue: String = value
 
-trait DSLPrologBuiltins:
+protected trait DSLPrologBuiltins:
   dsl: PrologDSL =>
   export AssociativitySpec.*
 
+  /** Returns a [[Directive]]
+   * 
+   * @param terms the arguments of the directive.
+   */
   @targetName("iff")
   def :-(terms: Term*): Directive = Directive(terms *)
 
+  /** Builds a var(X) [[Struct]].
+   * 
+   * @param term the argument of the structure
+   */
   def `var`(term: Term): Struct = Struct(Atom("var"), term)
+
+  /** Builds a nonvar(X) [[Struct]].
+   *
+   * @param term the argument of the structure
+   */
   def nonvar(term: Term): Struct = Struct(Atom("nonvar"), term)
+
+  /** Builds a atom(X) [[Struct]].
+   *
+   * @param term the argument of the structure
+   */
   def atom(term: Term): Struct = Struct(Atom("atom"), term)
+
+  /** Builds a number(X) [[Struct]].
+   *
+   * @param term the argument of the structure
+   */
   def number(term: Term): Struct = Struct(Atom("number"), term)
+
+  /** Builds an atomic(X) [[Struct]].
+   *
+   * @param term the argument of the structure
+   */
   def atomic(term: Term): Struct = Struct(Atom("atomic"), term)
+
+  /** Builds a ground(X) [[Struct]].
+   *
+   * @param term the argument of the structure
+   */
   def ground(term: Term): Struct = Struct(Atom("ground"), term)
 
+  /** Returns a member(t, l) [[Struct]].
+   * 
+   * @param term a term
+   * @param l a term that should unify to a list.
+   */
   def member(term: Term, l: Term): Struct = Struct(Atom("member"), term, l)
+
+  /** Returns an append(l1, l2) [[Struct]].
+   *
+   * @param l1 a term that should unify to a list
+   * @param l2 a term that should unify to a list.
+   */
   def append(l1: Term, l2: Term): Struct = Struct(Atom("append"), l1, l2)
 
+  /** Returns a dynamic(t1, t2, ...) [[Struct]].
+   * 
+   * @param indicators the indicators of the predicates.
+   */
   def dynamic(indicators: Indicator*): Struct =
     Directive(Struct(Atom("dynamic"), Conjunction.wrapIfNecessary(indicators*)))
 
   def clause(head: Term, body: Term): Struct = Struct(Atom("clause"), head, body)
+
+  /** Returns an asserta(X) [[Struct]].
+   * 
+   * @param clause the clause to assert.
+   */
   def asserta(clause: Term): Struct = Struct(Atom("asserta"), clause)
+
+  /** Returns an assertz(X) [[Struct]].
+   *
+   * @param clause the clause to assert.
+   */
   def assertz(clause: Term): Struct = Struct(Atom("assertz"), clause)
+
+  /** Returns an retract(X) [[Struct]].
+   *
+   * @param clause the clause to retract.
+   */
+
   def retract(clause: Term): Struct = Struct(Atom("retract"), clause)
 
+  /** Returns a functor(T, F, N) [[Struct]].
+   * 
+   * @param term a term.
+   * @param functor a term that should unify with the of the [[term]] functor.
+   * @param arity a term that should unify with the arity of the [[term]].
+   */
   def functor(term: Term, functor: Term, arity: Term): Struct =
     Struct(Atom("functor"), term, functor, arity)
 
+  /** Returns an arg(N, T, L) [[Struct]].
+   * 
+   * @param number a term that should unify with the position of the [[arg]] in [[term]].
+   * @param term a term
+   * @param arg a term that should unify the with [[number]]-th argument in [[term]].
+   */
   def arg(number: Term, term: Struct, arg: Term): Struct = Struct(Atom("arg"), number, term, arg)
 
+  /** Returns an atom_chars(A, L) [[Struct]].
+   * 
+   * @param atom a term that should unify to an atom.
+   * @param list a term that should unify to a list containing the characters of [[atom]].
+   */
   def atom_chars(atom: Term, list: Term): Struct = Struct(Atom("atom_chars"), atom, list)
+
+  /** Returns an number_chars(A, L) [[Struct]].
+   * 
+   * @param atom a term that should unify to an numeric constant
+   * @param list a term that should unify with a list containing the characters composing the constant.
+   */
   def number_chars(atom: Term, list: Term): Struct = Struct(Atom("number_chars"), atom, list)
 
+  /** The cut predicate */
   @targetName("cut")
   val `!`: Atom = Atom("!")
 
+  /** The repeat predicate */
   val repeat: Atom = Atom("repeat")
 
+  /** Builds a goal(G) [[Struct]].
+   *
+   * @param goal the argument of the structure
+   */
   def call(goal: Term): Struct = Struct(Atom("call"), goal)
+
+  /** Builds a once(G) [[Struct]].
+   *
+   * @param goal the argument of the structure
+   */
   def once(goal: Term): Struct = Struct(Atom("once"), goal)
+
+  /** Builds a not(G) [[Struct]].
+   *
+   * @param goal the argument of the structure
+   */
   def not(goal: Term): Struct = Struct(Atom("not"), goal)
 
+  /** Returns a findall(T, G, L) [[Struct]].
+   * 
+   * @param res 
+   * @param goal
+   * @param list a term that should unify to a list containing ???
+   */
   def findall(res: Term, goal: Term, list: Term): Struct = Struct(Atom("findall"), res, goal, list)
-
+  
+  /** Builds a \+(X) [[Struct]].
+   *
+   * @param goal the argument of the structure
+   */
   @targetName("naf")
   def !(goal: Term): Struct = Struct(Atom("\\+"), goal)
 
+  /** Returns an op(I, A, N) [[Struct]].
+   * 
+   * @param precedence
+   * @param associativity
+   * @param name
+   */
   def op(precedence: Constant.Numeric, associativity: AssociativitySpec, name: Atom): Struct =
     Struct(Atom("op"), precedence, associativity, name)
 
+  /** Returns a length(T, L) [[Struct]].
+   * 
+   * @param term
+   * @param len
+   */
   def length(term: Term, len: Term): Struct = Struct(Atom("length"), term, len)
+  
+  /** An empty list functor */
   val `[]`: Atom = Prolog.Functors.EMPTY_LIST
 

src/main/scala/io/github/kelvindev15/prolog/dsl/DeclarativeDSL.scala

@@ -7,43 +7,102 @@ import io.github.kelvindev15.prolog.core.{Struct, Term}
 import io.github.kelvindev15.prolog.dsl.DeclarativeDSL.{MutableDynamicTheoryWrapper, MutableTheoryWrapper}
 
 
-trait DeclarativeDSL:
+protected trait DeclarativeDSL:
   dsl: PrologDSL =>
   private var prologProgram: PrologProgram = PrologProgram()
 
+  /** Returns a new [[PrologProgram]].
+   *
+   * @param program a function that takes a [[PrologProgram]] as a context parameter and operates on it.
+   */
   def prolog(program: PrologProgram ?=> Unit): PrologProgram =
     given p: PrologProgram = prologProgram
     program
     prologProgram
 
+  /** Sets the static theory of a [[PrologProgram]].
+   *
+   * @param program the program whose static theory has to be set.
+   * @param theory a function that takes a [[MutableTheoryWrapper]] as a context parameter and operates on it
+   *               e.g to add or remove clauses.
+   */
   def staticTheory(using program: PrologProgram)(theory: MutableTheoryWrapper ?=> Unit): Unit =
     given t: MutableTheoryWrapper = MutableDynamicTheoryWrapper()
     theory
     prologProgram = program.setStaticTheory(t.theory)
 
+  /** Sets the dynamic theory of a [[PrologProgram]].
+   *
+   * @param program the program whose dynamic theory has to be set.
+   * @param theory  a function that takes a [[MutableDynamicTheoryWrapper]] as a context parameter and operates on it
+   *                e.g to add or remove clauses.
+   */
   def dynamicTheory(using program: PrologProgram)(theory: MutableDynamicTheoryWrapper ?=> Unit): Unit =
     given t: MutableDynamicTheoryWrapper = MutableDynamicTheoryWrapper()
     theory
     prologProgram = prologProgram.setDynamicTheory(t.theory)
 
+  /** Add an assert(X) clause to the [[dynamicTheory]] provided as a context parameter.
+   *
+   * @param dynamicTheory the theory to which the clause will be added.
+   * @param clause the clause to assert in the theory.
+   */
   def assert(using dynamicTheory: MutableDynamicTheoryWrapper)(clause: Clause): Unit =
     dynamicTheory add "assert"(clause)
 
+  /** Add an asserta(X) clause to the [[dynamicTheory]] provided as a context parameter.
+   *
+   * @param dynamicTheory the theory to which the clause will be added.
+   * @param clause        the clause to assert in the theory.
+   */
   def assertA(using dynamicTheory: MutableDynamicTheoryWrapper)(clause: Clause): Unit =
     dynamicTheory add "asserta"(clause)
 
+  /** Add an assertz(X) clause to the [[dynamicTheory]] provided as a context parameter.
+   *
+   * @param dynamicTheory the theory to which the clause will be added.
+   * @param clause        the clause to assert in the theory.
+   */
   def assertZ(using dynamicTheory: MutableDynamicTheoryWrapper)(clause: Clause): Unit =
     dynamicTheory add "assertz"(clause)
 
+  /** Add a rule to a [[MutableTheoryWrapper]] provided as a context parameter.
+   *
+   * @param theory the theory to which the rule will be added.
+   * @param rule the rule to add to the [[theory]].
+   */
   def rule(using theory: MutableTheoryWrapper)(rule: Rule): Unit = theory add rule
+
+  /** Add a fact to a [[MutableTheoryWrapper]] provided as a context parameter.
+   *
+   * @param theory the theory to which the fact will be added.
+   * @param fact the fact to add to the [[theory]].
+   */
   def fact(using theory: MutableTheoryWrapper)(fact: Fact): Unit = theory add fact
+
+  /** Add a directive to a [[MutableTheoryWrapper]] provided as a context parameter.
+   *
+   * @param theory the theory to which the directive will be added.
+   * @param directive   the directive to add to the [[theory]].
+   */
   def directive(using theory: MutableTheoryWrapper)(directive: Directive): Unit = theory add directive
+
+  /** Add a clause (either a rule, a fact or a directive) to a [[MutableTheoryWrapper]] provided as a context parameter.
+   *
+   * @param theory the theory to which the clause will be added.
+   * @param c   the clause to add to the [[theory]].
+   */
   def clause(using theory: MutableTheoryWrapper)(c: Clause): Unit = theory add c
 
+  /** Sets the goal of a [[PrologProgram]] provided as a context parameter.
+   *
+   * @param program the program whose goal will be set.
+   * @param g the goal to set in the [[program]].
+   */
   def goal(using program: PrologProgram)(g: Term): Unit =
     prologProgram = prologProgram withGoal g
 
-object DeclarativeDSL:
+private object DeclarativeDSL:
   trait MutableTheoryWrapper:
     var theory: Theory = Theory()
     def add(clause: Clause): Theory = { theory = theory add clause; theory }