Turn documentation in plugin_api into phpdoc

1 files changed, 105 insertions, 100 deletions

diff --git a/ratatoeskr/sys/plugin_api.php b/ratatoeskr/sys/plugin_api.php
index 18e129b..c286fdc 100644
--- a/ratatoeskr/sys/plugin_api.php
+++ b/ratatoeskr/sys/plugin_api.php
@@ -9,31 +9,29 @@
  * See "ratatoeskr/licenses/ratatoeskr" for more information.
  */
 
+use r7r\ste\STECore;
+
 require_once(dirname(__FILE__) . "/models.php");
 require_once(dirname(__FILE__) . "/textprocessors.php");
 require_once(dirname(__FILE__) . "/../frontend.php");
 
-/*
- * Constant: APIVERSION
+/**
  * The current API version (6).
  */
 define("APIVERSION", 6);
 
-/*
- * Array: $api_compat
- * Array of API versions, this version is compatible to (including itself).
+/**
+ * @var int[] Array of API versions, this version is compatible to (including itself).
  */
 $api_compat = [3, 4, 5, 6];
 
 $url_handlers = []; /* master URL handler */
 
-/*
- * Function: register_url_handler
- * Register an URL handler. See <ratatoeskr/sys/urlprocess.php> for more details.
+/**
+ * Register an URL handler. See ratatoeskr/sys/urlprocess.php for more details.
  *
- * Parameters:
- *  $name - The name of the new URL
- *  $callback - The Function to be called (see <url_process>).
+ * @param string $name The name of the new URL
+ * @param callable $callback The Function to be called (see <url_process>).
  */
 function register_url_handler($name, callable $callback)
 {
@@ -45,32 +43,27 @@ $pluginpages_handlers = [];
 
 $articleeditor_plugins = [];
 
-/*
- * Class: RatatoeskrPlugin
+/**
  * An abstract class to be extended in order to write your own Plugin.
  */
 abstract class RatatoeskrPlugin
 {
     private $id;
 
-    /*
-     * Variables: Protected variables
-     *
-     * $kvstorage - The Key-Value-Storage for the Plugin.
-     * $ste - Access to the global STECore object.
-     * $rel_path_to_root - Relative URL to the root of the page.
-     */
+    /** @var PluginKVStorage The Key-Value-Storage for the Plugin */
     protected $kvstorage;
+
+    /** @var STECore Access to the global STECore object */
     protected $ste;
+
+    /** @var string Relative URL to the root of the page */
     protected $rel_path_to_root;
 
-    /*
-     * Constructor: __construct
+    /**
      * Performing some neccessary initialisation stuff.
      * If you are overwriting this function, you *really* should call parent::__construct!
      *
-     * Parameters:
-     *  $id - The ID of the plugin (not the name).
+     * @param int $id - The ID of the plugin (not the name).
      */
     public function __construct($id)
     {
@@ -82,96 +75,103 @@ abstract class RatatoeskrPlugin
         $this->rel_path_to_root = $rel_path_to_root;
     }
 
-    /*
-     * Functions: Some getters
-     *
-     * get_id - get the Plugin-ID
-     * get_custompriv_dir - Get path to the custompriv directory of your plugin.
-     * get_custompub_dir - Get path to the custompub directory of your plugin.
-     * get_custompub_url - Get URL (can be accessed from the web) to the custompub directory of your plugin.
-     * get_template_dir - Get path to your template directory to be used with STE.
+    /**
+     * Get the Plugin-ID
+     * @return int
      */
     final public function get_id()
     {
         return $this->id;
     }
+
+    /**
+     * Get path to the custompriv directory of your plugin.
+     * @return string
+     */
     final protected function get_custompriv_dir()
     {
         return SITE_BASE_PATH . "/ratatoeskr/plugin_extradata/private/" . $this->id;
     }
+
+    /**
+     * Get path to the custompub directory of your plugin.
+     * @return string
+     */
     final protected function get_custompub_dir()
     {
         return SITE_BASE_PATH . "/ratatoeskr/plugin_extradata/public/" . $this->id;
     }
+
+    /**
+     * Get URL (can be accessed from the web) to the custompub directory of your plugin.
+     * @return string
+     */
     final protected function get_custompub_url()
     {
         return $GLOBALS["rel_path_to_root"] . "/ratatoeskr/plugin_extradata/public/" . $this->id;
     }
+
+    /**
+     * Get path to your template directory to be used with STE.
+     * @return string
+     */
     final protected function get_template_dir()
     {
         return "/plugintemplates/" . $this->id;
     }
 
-    /*
-     * Function: register_url_handler
+    /**
      * Register a URL handler
      *
-     * Parameters:
-     *  $name - Name of URL
-     *  $fx   - The function.
+     * @param string $name Name of URL
+     * @param callable $fx The function.
      */
     final protected function register_url_handler($name, $fx)
     {
         register_url_handler($name, $fx);
     }
 
-    /*
-     * Function: register_ste_tag
+    /**
      * Register a custom STE tag.
      *
-     * Parameters:
-     *  $name - Name of your new STE tag.
-     *  $fx   - Function to register with this tag.
+     * @param string $name Name of your new STE tag.
+     * @param callable $fx Function to register with this tag.
      */
     final protected function register_ste_tag($name, $fx)
     {
         $this->ste->register_tag($name, $fx);
     }
 
-    /*
-     * Function: register_textprocessor
+    /**
      * Register a textprocessor.
      *
-     * Parameters:
-     *  $name               - The name of the textprocessor-
-     *  $fx                 - Function to register (function($input), returns HTML).
-     *  $visible_in_backend - Should this textprocessor be visible in the backend? Defaults to True.
+     * @param string $name The name of the textprocessor-
+     * @param callable $fx Function to register (function($input), returns HTML).
+     * @param bool $visible_in_backend Should this textprocessor be visible in the backend? Defaults to True.
      */
     final protected function register_textprocessor($name, $fx, $visible_in_backend=true)
     {
         textprocessor_register($name, $fx, $visible_in_backend);
     }
 
-    /*
-     * Function: register_comment_validator
+    /**
      * Register a comment validator.
      *
-     * A comment validator is a function, that checks the $_POST fields and decides whether a comment should be stored or not (throws an <CommentRejected> exception with the rejection reason as the message).
+     * A comment validator is a function, that checks the $_POST fields and decides whether a comment should be stored
+     * or not (throws an (@see CommentRejected} exception with the rejection reason as the message).
      *
-     * Parameters:
-     *  $fx - Validator function.
+     * @param callable $fx Validator function.
      */
     final protected function register_comment_validator($fx)
     {
         global $comment_validators;
         $comment_validators[] = $fx;
     }
-    /*
-     * Function: register_on_comment_store
+
+    /**
      * Register a function that will be called, after a comment was saved.
      *
-     * Parameters:
-     *  $fx - Function, that accepts one parameter (a <Comment> object).
+     * @param callable $fx Function, that accepts one parameter (a {@see Comment} object).
      */
     final protected function register_on_comment_store($fx)
     {
@@ -179,20 +179,19 @@ abstract class RatatoeskrPlugin
         $on_comment_store[] = $fx;
     }
 
-    /*
-     * Function: register_backend_pluginpage
+    /**
      * Register a backend subpage for your plugin.
      *
-     * Parameters:
-     *  $label - The label for the page.
-     *  $fx    - A function for <url_process>.
+     * Your $fx should output output the result of a STE template, which should
+     * load "/systemtemplates/master.html" and overwrite the "content" section.
      *
-     * Your $fx should output output the result of a STE template, which should load "/systemtemplates/master.html" and overwrite the "content" section.
+     * If you need a URL to your pluginpage, you can use {@see RatatoeskrPlugin::get_backend_pluginpage_url()} and the
+     * STE variable $rel_path_to_pluginpage.
      *
-     * If you need a URL to your pluginpage, you can use <get_backend_pluginpage_url> and the STE variable $rel_path_to_pluginpage.
+     * See also {@see RatatoeskrPlugin::prepare_backend_pluginpage()}
      *
-     * See also:
-     *  <prepare_backend_pluginpage>
+     * @param string $label The label for the page.
+     * @param callable $fx A function for <url_process>.
      */
     final protected function register_backend_pluginpage($label, $fx)
     {
@@ -210,20 +209,23 @@ abstract class RatatoeskrPlugin
         };
     }
 
-    /*
-     * Function: register_articleeditor_plugin
+    /**
      * Register a plugin for the article editor in the backend.
      *
-     * Parameters:
-     *  $label    - The label for the plugin.
-     *  $fx       - A function that will be called during the articleeditor.
-     *              This function must accept these parameters:
-     *              * $article       - An <Article> object or NULL, if no Article is edited right now.
-     *              * $about_to_save - If True, the article is about to be saved.
-     *                                 If you want to veto the saving, return the rejection reason as a string.
-     *                                 If everything is okay and you need to save additional data, return a callback function that accepts the saved <Article> object (that callback should also write data back to the template, if necessary).
-     *                                 If everything is okay and you do not need to save additional data, return NULL.
-     *  $template - The name of the template to display in the editor, relative to your template directory. If you do not want to display anything, you can set ths to NULL.
+     * You $fx function must take two parameters:
+     *
+     * - $article:
+     *   An {@see Article} object or null, if no Article is edited right now.
+     * - $about_to_save:
+     *   If true, the article is about to be saved.
+     *   If you want to veto the saving, return the rejection reason as a string.
+     *   If everything is okay and you need to save additional data, return a callback function that
+     *   accepts the saved {@see Article} object (that callback should also write data back to the template, if necessary).
+     *   If everything is okay and you do not need to save additional data, return NULL.
+     *
+     * @param string $label The label for the plugin.
+     * @param callable $fx A function that will be called during the articleeditor. See above for a detailed explanation.
+     * @param string|null $template The name of the template to display in the editor, relative to your template directory. If you do not want to display anything, you can set ths to NULL.
      */
     final protected function register_articleeditor_plugin($label, $fx, $template)
     {
@@ -237,12 +239,10 @@ abstract class RatatoeskrPlugin
         ];
     }
 
-    /*
-     * Function: get_backend_pluginpage_url
+    /**
      * Get the URL to your backend plugin page.
      *
-     * Returns:
-     *  The URL to your backend plugin page.
+     * @return string The URL to your backend plugin page.
      */
     final protected function get_backend_pluginpage_url()
     {
@@ -250,23 +250,18 @@ abstract class RatatoeskrPlugin
         return "$rel_path_to_root/backend/pluginpages/p{$this->id}";
     }
 
-    /*
-     * Function: get_article_extradata
-     * Get the <ArticleExtradata> object for this plugin and the given article.
-     *
-     * Parameters:
-     *  $article - An <Article> object.
+    /**
+     * Get the {@see ArticleExtradata} object for this plugin and the given article.
      *
-     * Returns:
-     *  An <ArticleExtradata> object for this plugin and the given article.
+     * @param Article $article
+     * @return ArticleExtradata
      */
     final protected function get_article_extradata($article)
     {
         return new ArticleExtradata($article->get_id(), $this->id);
     }
 
-    /*
-     * Function: prepare_backend_pluginpage
+    /**
      * Automatically sets the page title and highlights the menu-entry of your backend subpage.
      */
     final protected function prepare_backend_pluginpage()
@@ -276,27 +271,37 @@ abstract class RatatoeskrPlugin
         $this->ste->vars["pagetitle"] = $this->ste->vars["pluginpages"][$this->id];
     }
 
-    /*
-     * Functions: Functions that are called at special events
-     *
-     * init      - Will be called after plugin is loaded. You should register your stuff here.
-     * atexit    - Will be called, when Ratatöskr will exit.
-     * install   - Will be called after installation. If your plugin needs to initialize some database stuff or generate files, this is the right function.
-     * uninstall - Will be called during uninstallation. If you used the install function you should undo your custom installation stuff.
-     * update    - Will be called after your plugin was updated to a new version.
+    /**
+     * Will be called after plugin is loaded. You should register your stuff here.
      */
     public function init()
     {
     }
+
+    /**
+     * Will be called, when Ratatöskr will exit.
+     */
     public function atexit()
     {
     }
+
+    /**
+     * Will be called after installation. If your plugin needs to initialize some database stuff or generate files, this is the right function.
+     */
     public function install()
     {
     }
+
+    /**
+     * Will be called during uninstallation. If you used the install function you should undo your custom installation stuff.
+     */
     public function uninstall()
     {
     }
+
+    /**
+     * Will be called after your plugin was updated to a new version.
+     */
     public function update()
     {
     }