Clean up code and improve documentation

This switches the code documentation genarator (we're now using phpdoc
instead of NaturalDoc).

Also various small code cleanup tasks:

- Remove unused code
- Get rid of `and` / `or`, we're using `&&` / `||` now
- Adding missing return values
- Helping PhpStorm to detect some dynamically called functions
  (mark_builtin_callable in Transcompiler)
- Reword transcompiling => compiling in documentation

1 files changed, 108 insertions, 69 deletions

diff --git a/src/ste/STECore.php b/src/ste/STECore.php
index 13fb2f6..40d680a 100644
--- a/src/ste/STECore.php
+++ b/src/ste/STECore.php
@@ -1,43 +1,64 @@
 <?php
 
-// File: STECore.php
-
-// Namespace: kch42\ste
 namespace kch42\ste;
 
-/*
- * Class: STECore
+use Exception;
+
+/**
  * The Core of STE
  */
 class STECore
 {
+    /** @var callable[] */
     private $tags;
+
+    /** @var StorageAccess */
     private $storage_access;
+
+    /** @var string */
     private $cur_tpl_dir;
+
+    /** @var Scope */
     public $scope;
 
-    /*
-     * Variables: Public variables
-     *
-     * $blocks - Associative array of blocks (see the language definition).
-     * $blockorder - The order of the blocks (an array)
-     * $mute_runtime_errors - If true (default) a <RuntimeError> exception will result in no output from the tag, if false a error message will be written to output.
-     * $fatal_error_on_missing_tag - If true, STE will throw a <FatalRuntimeError> if a tag was called that was not registered, otherwise (default) a regular <RuntimeError> will be thrown and automatically handled by STE (see <$mute_runtime_errors>).
-     * $vars - Variables in the top scope of the template.
+    /**
+     * @var array
+     * Associative array of blocks (see the language definition).
      */
     public $blocks;
+
+    /**
+     * @var array
+     * The order of the blocks (an array)
+     */
     public $blockorder;
+
+    /**
+     * @var bool
+     * If true (default) a {@see RuntimeError} exception will result in no
+     * output from the tag, if false a error message will be written to output.
+     */
     public $mute_runtime_errors = true;
+
+    /**
+     * @var bool
+     * If true, STE will throw a {@see FatalRuntimeError} if a tag was called
+     * that was not registered, otherwise (default) a regular
+     * {@see RuntimeError} will be thrown and automatically handled by STE
+     * (see {@see STECore::$mute_runtime_errors}).
+     */
     public $fatal_error_on_missing_tag = false;
+
+    /**
+     * @var array
+     * Variables in the top scope of the template.
+     */
     public $vars;
 
-    /*
-     * Constructor: __construct
-     *
-     * Parameters:
-     *  $storage_access - An Instance of a <StorageAccess> implementation.
+    /**
+     * @param StorageAccess $storage_access
      */
-    public function __construct($storage_access)
+    public function __construct(StorageAccess $storage_access)
     {
         $this->storage_access = $storage_access;
         $this->cur_tpl_dir = "/";
@@ -50,42 +71,47 @@ class STECore
         $this->scope->vars =& $this->vars;
     }
 
-    /*
-     * Function: register_tag
+    /**
      * Register a custom tag.
      *
      * Parameters:
-     *  $name - The name of the tag.
-     *  $callback - A callable function (This must take three parameters: The <STECore> instance, an associative array of parameters, and a function representing the tags content(This expects the <STECore> instance as its only parameter and returns its text result, i.e to get the text, you neeed to call this function with the <STECore> instance as a parameter)).
+     * @param string $name The name of the tag.
+     * @param callable $callback A callable function
+     *                           Must take three parameters:
      *
-     * Throws:
-     *  An Exception if the tag could not be registered (if $callback is not callable or if $name is empty)
+     *                           The {@see STECore} instance,
+     *                           an associative array of parameters,
+     *                           and a function representing the tags content
+     *                           (This expects the {@see STECore} instance as
+     *                           its only parameter and returns its text result,
+     *                           i.e to get the text, you need to call this
+     *                           function with the {@see STECore} instance as a
+     *                           parameter).
+     *
+     * @throws Exception If the tag could not be registered (if $callback is not callable or if $name is empty)
      */
     public function register_tag($name, $callback)
     {
         if (!is_callable($callback)) {
-            throw new \Exception("Can not register tag \"$name\", not callable.");
+            throw new Exception("Can not register tag \"$name\", not callable.");
         }
         if (empty($name)) {
-            throw new \Exception("Can not register tag, empty name.");
+            throw new Exception("Can not register tag, empty name.");
         }
         $this->tags[$name] = $callback;
     }
 
-    /*
-     * Function: call_tag
+    /**
      * Calling a custom tag (builtin ones can not be called)
      *
-     * Parameters:
-     *  $name - The Tag's name
-     *  $params - Associative array of parameters
-     *  $sub - A callable function (expecting an <STECore> instance as it's parameter) that represents the tag's content.
+     * @param string $name The Tag's name
+     * @param array $params Associative array of parameters
+     * @param callable $sub A callable function (expecting an {@see STECore} instance as it's parameter) that represents the tag's content.
      *
-     * Throws:
-     *  Might throw a <FatalRuntimeError> (see <$fatal_error_on_missing_tag>.
+     * @throws FatalRuntimeError see {@see STECore::$fatal_error_on_missing_tag}.
      *
-     * Returns:
-     *  The output of the tag or, if a <RuntimeError> was thrown, the appropiate result (see <$mute_runtime_errors>).
+     * @return string The output of the tag or, if a {@see RuntimeError} was thrown, the appropriate result
+     *                (see {@see STECore::$mute_runtime_errors}).
      */
     public function call_tag($name, $params, $sub)
     {
@@ -103,28 +129,37 @@ class STECore
                 return "RuntimeError occurred on tag '$name': " . $e->getMessage();
             }
         }
+
+        return "";
     }
 
+    /**
+     * {@see Calc::calc()}
+     *
+     * @param string $expression
+     * @return float|int
+     * @throws RuntimeError
+     */
     public function calc($expression)
     {
         return Calc::calc($expression);
     }
 
-    /*
-     * Function: exectemplate
-     * Executes a template and returns the result. The huge difference to <load> is that this function will also output all blocks.
+    /**
+     * Executes a template and returns the result.
      *
-     * Parameters:
-     *  $tpl - The name of the template to execute.
+     * The huge difference to {@see STECore::load()} is that this function will also output all blocks.
      *
-     * Throws:
-     *  * A <CantLoadTemplate> exception if the template could not be loaded.
-     *  * A <ParseCompileError> if the template could not be parsed or transcompiled.
-     *  * A <FatalRuntimeError> if a tag threw it or if a tag was not found and <$fatal_error_on_missing_tag> is true.
-     *  * Might also throw different exceptions, if a external tag threw it (but they should use <RuntimeError> or <FatalRuntimeError> to make it possible for STE to handle them correctly).
+     * @param string $tpl The name of the template to execute.
      *
-     * Returns:
-     *  The output of the template.
+     * @throws CantLoadTemplate If the template could not be loaded.
+     * @throws ParseCompileError If the template could not be parsed or compiled.
+     * @throws FatalRuntimeError If a tag threw it or if a tag was not found and <$fatal_error_on_missing_tag> is true.
+     *
+     * Might also throw different exceptions, if a external tag threw it
+     * (but they should use {@see RuntimeError} or {@see FatalRuntimeError} to make it possible for STE to handle them correctly).
+     *
+     * @return string The output of the template.
      */
     public function exectemplate($tpl)
     {
@@ -211,22 +246,21 @@ class STECore
         return $this->scope->get_var_by_name($name);
     }
 
-    /*
-     * Function: load
-     * Load a template and return its result (blocks not included, use <exectemplate> for this).
+    /**
+     * Load a template and return its result (blocks not included, use {@see STECore::exectemplate} for this).
      *
-     * Parameters:
-     *  $tpl - The name of the template to be loaded.
-     *  $quiet - If true, do not output anything and do not modify the blocks. This can be useful to load custom tags that are programmed in the STE Template Language. Default: false.
+     * @param string $tpl The name of the template to be loaded.
+     * @param bool $quiet If true, do not output anything and do not modify the blocks. This can be useful to load custom tags that are programmed in the STE Template Language. Default: false.
      *
-     * Throws:
-     *  * A <CantLoadTemplate> exception if the template could not be loaded.
-     *  * A <ParseCompileError> if the template could not be parsed or transcompiled.
-     *  * A <FatalRuntimeError> if a tag threw it or if a tag was not found and <$fatal_error_on_missing_tag> is true.
-     *  * Might also throw different exceptions, if a external tag threw it (but they should use <RuntimeError> or <FatalRuntimeError> to make it possible for STE to handle them correctly).
+     * @throws CantLoadTemplate If the template could not be loaded.
+     * @throws CantSaveTemplate If the template could not be saved.
+     * @throws ParseCompileError If the template could not be parsed or compiled.
+     * @throws FatalRuntimeError If a tag threw it or if a tag was not found and {@see STECore::$fatal_error_on_missing_tag} is true.
      *
-     * Returns:
-     *  The result of the template (if $quiet == false).
+     * Might also throw different exceptions, if a external tag threw it
+     * (but they should use {@see RuntimeError} or {@see FatalRuntimeError} to make it possible for STE to handle them correctly).
+     *
+     * @return string|null The result of the template (if $quiet == false).
      */
     public function load($tpl, $quiet = false)
     {
@@ -238,7 +272,7 @@ class STECore
             $tpl = $this->cur_tpl_dir . "/" . $tpl;
         }
         $pathex = array_filter(explode("/", $tpl), function ($s) {
-            return ($s != ".") and (!empty($s));
+            return $s != "." && !empty($s);
         });
         $pathex = array_merge($pathex);
         while (($i = array_search("..", $pathex)) !== false) {
@@ -277,26 +311,31 @@ class STECore
         if ($quiet) {
             $this->blocks     = $blocks_back;
             $this->blockorder = $blockorder_back;
+
+            return null;
         } else {
             return $output;
         }
     }
 
     /*
-     * Function: evalbool
      * Test, if a text represents false (an empty / only whitespace text) or true (everything else).
      *
-     * Parameters:
-     *  $txt - The text to test.
+     * @param string $txt The text to test.
      *
-     * Returns:
-     *  true/false.
+     * @return bool
      */
     public function evalbool($txt)
     {
         return trim(@(string)$txt) != "";
     }
 
+    /**
+     * Internal function for implementing tag content and custom tags.
+     *
+     * @param callable $fx
+     * @return \Closure
+     */
     public function make_closure($fx)
     {
         $bound_scope = $this->scope;
@@ -312,7 +351,7 @@ class STECore
                 $result = call_user_func_array($fx, $args);
                 $ste->scope = $prev;
                 return $result;
-            } catch (\Exception $e) {
+            } catch (Exception $e) {
                 $ste->scope = $prev;
                 throw $e;
             }