Merge pull request #18 from NathanFallet/feature/documentation

Javadoc

src/main/kotlin/me/nathanfallet/makth/actions/IfAction.kt

@@ -7,6 +7,13 @@ import me.nathanfallet.makth.interfaces.Value
 import me.nathanfallet.makth.lexers.AlgorithmLexer.IncorrectArgumentCountException
 import me.nathanfallet.makth.resolvables.Context
 
+/**
+ * Action that executes a list of actions if a condition is true,
+ * or another list of actions otherwise.
+ * @param condition Condition to check
+ * @param actions Actions to execute if condition is true
+ * @param elseActions Actions to execute if condition is false
+ */
 data class IfAction @JvmOverloads constructor(
         val condition: Value,
         val actions: List<Action>,
@@ -15,6 +22,11 @@ data class IfAction @JvmOverloads constructor(
 
     companion object {
 
+        /**
+         * Handler for if action
+         * @param args List of arguments
+         * @return Action created from arguments
+         */
         @JvmStatic
         fun handler(args: List<Value>): Action {
             if (args.count() != 1) {

src/main/kotlin/me/nathanfallet/makth/actions/PrintAction.kt

@@ -5,10 +5,19 @@ import me.nathanfallet.makth.interfaces.Action
 import me.nathanfallet.makth.interfaces.Value
 import me.nathanfallet.makth.resolvables.Context
 
+/**
+ * Action that prints values
+ * @param values Values to print
+ */
 data class PrintAction(val values: List<Value>) : Action {
 
     companion object {
 
+        /**
+         * Handler for print action
+         * @param args Arguments of the action
+         * @return Action created from the arguments
+         */
         @JvmStatic
         fun handler(args: List<Value>): Action {
             return PrintAction(args.toList())

src/main/kotlin/me/nathanfallet/makth/actions/SetAction.kt

@@ -8,10 +8,20 @@ import me.nathanfallet.makth.lexers.AlgorithmLexer.IncorrectArgumentTypeExceptio
 import me.nathanfallet.makth.resolvables.Context
 import me.nathanfallet.makth.resolvables.Variable
 
+/**
+ * Action that sets a variable
+ * @param identifier Identifier of the variable to set
+ * @param value Value to set
+ */
 data class SetAction(val identifier: String, val value: Value) : Action {
 
     companion object {
 
+        /**
+         * Handler for set action
+         * @param args Arguments of the action
+         * @return Action created from the arguments
+         */
         @JvmStatic
         fun handler(args: List<Value>): Action {
             if (args.count() != 2) {

src/main/kotlin/me/nathanfallet/makth/actions/WhileAction.kt

@@ -7,10 +7,20 @@ import me.nathanfallet.makth.interfaces.Value
 import me.nathanfallet.makth.lexers.AlgorithmLexer.IncorrectArgumentCountException
 import me.nathanfallet.makth.resolvables.Context
 
+/**
+ * Action that executes a list of actions while a condition is true.
+ * @param condition Condition to check
+ * @param actions Actions to execute while condition is true
+ */
 data class WhileAction(val condition: Value, val actions: List<Action>) : Action {
 
     companion object {
 
+        /**
+         * Handler for while action
+         * @param args List of arguments
+         * @return Action created from arguments
+         */
         @JvmStatic
         fun handler(args: List<Value>): Action {
             if (args.count() != 1) {

src/main/kotlin/me/nathanfallet/makth/extensions/BooleanExtension.kt

@@ -4,6 +4,10 @@ import me.nathanfallet.makth.interfaces.Value
 import me.nathanfallet.makth.resolvables.Context
 import me.nathanfallet.makth.resolvables.Variable
 
+/**
+ * Boolean value
+ * @param value Boolean value
+ */
 data class BooleanValue(val value: Boolean) : Value {
 
     override fun compute(context: Context): Value {

src/main/kotlin/me/nathanfallet/makth/extensions/StringExtension.kt

@@ -4,6 +4,10 @@ import me.nathanfallet.makth.interfaces.Value
 import me.nathanfallet.makth.resolvables.Context
 import me.nathanfallet.makth.resolvables.Variable
 
+/**
+ * String value
+ * @param value String value
+ */
 data class StringValue(val value: String, val latex: Boolean = false) : Value {
 
     override fun compute(context: Context): Value {

src/main/kotlin/me/nathanfallet/makth/interfaces/Action.kt

@@ -3,16 +3,31 @@ package me.nathanfallet.makth.interfaces
 import me.nathanfallet.makth.resolvables.Context
 import me.nathanfallet.makth.resolvables.Variable
 
+/**
+ * Interface for all actions that can be executed
+ */
 interface Action {
 
     // Errors
 
+    /**
+     * Base class for all execution errors
+     * @param action Action that failed
+     * @param context Context of the action
+     * @param message Error message
+     */
     open class ExecutionException(
         val action: Action,
         val context: Context,
         message: String
     ) : Exception(message)
 
+    /**
+     * Exception thrown when one (or more) variable is not found
+     * @param action Action that failed
+     * @param context Context of the action
+     * @param variable Variables that were not found
+     */
     open class UnknownVariablesException(
         action: Action,
         context: Context,
@@ -22,6 +37,12 @@ interface Action {
         "Unknown variable(s): ${variables.joinToString(", ") { it.name }}"
     )
 
+    /**
+     * Exception thrown when a variable is not a boolean
+     * @param action Action that failed
+     * @param context Context of the action
+     * @param value Value that is not a boolean
+     */
     open class NotABooleanException(
         action: Action,
         context: Context,
@@ -33,9 +54,18 @@ interface Action {
 
     // Interface
 
+    /**
+     * Execute the action in the given context
+     * @param context Context of the action
+     * @return New context after the action was executed
+     */
     @Throws(ExecutionException::class)
     fun execute(context: Context): Context
 
+    /**
+     * Convert the action to a string that can be parsed by the algorithm lexer
+     * @return String representation of the action
+     */
     fun toAlgorithmString(): String
 
 }

src/main/kotlin/me/nathanfallet/makth/interfaces/Output.kt

@@ -1,3 +1,6 @@
 package me.nathanfallet.makth.interfaces
 
+/**
+ * Interface for all outputs of actions
+ */
 interface Output

src/main/kotlin/me/nathanfallet/makth/interfaces/Value.kt

@@ -3,19 +3,48 @@ package me.nathanfallet.makth.interfaces
 import me.nathanfallet.makth.resolvables.Context
 import me.nathanfallet.makth.resolvables.Variable
 
+/**
+ * Interface for all values that can be computed
+ */
 interface Value: Output {
 
+    /**
+     * Convert the value to a string that can be parsed by the algorithm lexer
+     * @return Algorithm string
+     */
     fun toAlgorithmString(): String {
         return toRawString()
     }
 
+    /**
+     * Compute the value in the given context
+     * @param context Context of the value
+     * @return Computed value
+     */
     fun compute(context: Context): Value
 
+    /**
+     * Convert the value to a raw string
+     * @return Raw string
+     */
     fun toRawString(): String
+
+    /**
+     * Convert the value to a LaTeX string
+     * @return LaTeX string
+     */
     fun toLaTeXString(): String
 
+    /**
+     * Extract all variables from the value
+     * @return Set of variables
+     */
     fun extractVariables(): Set<Variable>
 
+    /**
+     * Get the precedence of the value, used for braces
+     * @return Precedence
+     */
     fun getMainPrecedence(): Int {
         return Int.MAX_VALUE
     }

src/main/kotlin/me/nathanfallet/makth/lexers/AlgorithmLexer.kt

@@ -9,30 +9,66 @@ import me.nathanfallet.makth.interfaces.Action
 import me.nathanfallet.makth.interfaces.Value
 import me.nathanfallet.makth.resolvables.Context
 
+/**
+ * A lexer for algorithms
+ * @param content Content of the algorithm
+ */
 class AlgorithmLexer(private var content: String) {
 
     // Errors
 
+    /**
+     * Base class for all syntax errors
+     * @param message Error message
+     */
     open class SyntaxException(message: String) : Exception(message)
 
+    /**
+     * Exception thrown when an unknown keyword is found
+     * @param keyword Unknown keyword
+     */
     open class UnknownKeywordException(val keyword: String) :
             SyntaxException("Unknown keyword: $keyword")
 
+    /**
+     * Exception thrown when an unexpected keyword is found
+     * @param keyword Unexpected keyword
+     */
     open class UnexpectedKeywordException(val keyword: String) :
             SyntaxException("Unexpected keyword: $keyword")
 
+    /**
+     * Exception thrown when an unexpected brace is found
+     * @param character Unexpected brace
+     */
     open class UnexpectedBraceException(val character: String) :
             SyntaxException("Unexpected brace: $character")
 
+    /**
+     * Exception thrown when an unexpected slash is found
+     * @param character Unexpected slash
+     */
     open class UnexpectedSlashException(val character: String) :
             SyntaxException("Unexpected slash: $character")
 
+    /**
+     * Exception thrown when an incorrect argument count is found
+     * @param keyword Keyword
+     * @param count Argument count
+     * @param expected Expected argument count
+     */
     open class IncorrectArgumentCountException(
             val keyword: String,
             val count: Int,
             val expected: Int
     ) : SyntaxException("Incorrect argument count for $keyword, got $count, expected $expected")
 
+    /**
+     * Exception thrown when an incorrect argument type is found
+     * @param keyword Keyword
+     * @param value Argument value
+     * @param expected Expected argument type
+     */
     open class IncorrectArgumentTypeException(
             val keyword: String,
             val value: Value,
@@ -65,18 +101,33 @@ class AlgorithmLexer(private var content: String) {
                     "while" to WhileAction::handler
             )
 
+    /**
+     * Register a keyword handler
+     * @param keyword Keyword to register
+     * @param handler Handler to register
+     * @return This lexer, with the new handler registered
+     */
     fun registerKeyword(keyword: String, handler: (List<Value>) -> Action): AlgorithmLexer {
         keywordHandlers += mapOf(keyword to handler)
         return this
     }
 
+    /**
+     * Register multiple keyword handlers
+     * @param keywords Keywords to register
+     * @return This lexer, with the new handlers registered
+     */
     fun registerKeywords(keywords: Map<String, (List<Value>) -> Action>): AlgorithmLexer {
         keywordHandlers += keywords
         return this
     }
 
     // Parse an algorithm
 
+    /**
+     * Parse an algorithm, and return a list of actions
+     * @return List of actions
+     */
     @Throws(SyntaxException::class)
     fun execute(): List<Action> {
         // For each character of the string