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, 20 insertions, 31 deletions

diff --git a/src/ste/StorageAccess.php b/src/ste/StorageAccess.php
index e2e8727..38dea7e 100644
--- a/src/ste/StorageAccess.php
+++ b/src/ste/StorageAccess.php
@@ -1,56 +1,45 @@
 <?php
 
-// File: StorageAccess.php
-
-// Namespace: kch42\ste
 namespace kch42\ste;
 
-/*
- * Class: StorageAccess
- * An interface.
+/**
  * A StorageAccess implementation is used to access the templates from any storage.
  * This means, that you are not limited to store the Templates inside directories, you can also use a database or something else.
  */
 interface StorageAccess
 {
-    /*
-     * Constants: Template modes
-     *
-     * MODE_SOURCE - The Templates source
-     * MODE_TRANSCOMPILED - The transcompiled template
-     */
+    /** @var int The template's source */
     const MODE_SOURCE        = 0;
+
+    /** @var int The compiled template */
     const MODE_TRANSCOMPILED = 1;
 
-    /*
-     * Function: load
+    /**
      * Loading a template.
      *
-     * Parameters:
-     *  $tpl - The name of the template.
-     *  &$mode - Which mode is preferred? One of the <Template modes>.
-     *           If <MODE_SOURCE>, the raw sourcecode is expected, if <MODE_TRANSCOMPILED> the transcompiled template *as a callable function* (expecting an <STECore> instance as first parameter) is expected.
-     *           If the transcompiled version is not available or older than the source, you can set this parameter to <MODE_SOURCE> and return the source.
+     * @param string $tpl The name of the template.
+     * @param string &$mode Which mode is preferred? One of the MODE_* constants.
+     *                      If {@see StorageAccess::MODE_SOURCE}, the raw sourcecode is expected,
+     *                      if {@see StorageAccess::MODE_TRANSCOMPILED} the compiled template
+     *                      *as a callable function* (expecting an {@see STECore} instance as first parameter) is expected.
+     *
+     *                      If the compiled version is not available or older than the source, you can set this
+     *                      parameter to {@see StorageAccess::MODE_SOURCE} and return the source.
      *
-     * Throws:
-     *  A <CantLoadTemplate> exception if the template could not be loaded.
+     * @throws CantLoadTemplate If the template could not be loaded.
      *
-     * Returns:
-     *  Either the sourcecode or a callable function (first, and only parameter: an <STECore> instance).
+     * @return string|callable Either the sourcecode or a callable function (first, and only parameter: an {@see STECore} instance).
      */
     public function load($tpl, &$mode);
 
-    /*
-     * Function: save
+    /**
      * Saves a template.
      *
-     * Throws:
-     *  A <CantSaveTemplate> exception if the template could not be saved.
+     * @param string $tpl -The name of the template.
+     * @param string $data - The data to be saved.
+     * @param int $mode - One of the MODE_* constants.
      *
-     * Parameters:
-     *  $tpl -The name of the template.
-     *  $data - The data to be saved.
-     *  $mode - A <Template mode> constant.
+     * @throws CantSaveTemplate If the template could not be saved.
      */
     public function save($tpl, $data, $mode);
 }