PHPDocs and some improvements

18 files changed, 63 insertions, 26 deletions

diff --git a/bin/gittool.php b/bin/gittool.php
index 7991a9997..cbadb5bfa 100755
--- a/bin/gittool.php
+++ b/bin/gittool.php
@@ -206,12 +206,13 @@ class GitToolCLI extends DokuCLI {
      * Install extension from the given download URL
      *
      * @param string $ext
-     * @return bool
+     * @return bool|null
      */
     private function downloadExtension($ext) {
         /** @var helper_plugin_extension_extension $plugin */
         $plugin = plugin_load('helper', 'extension_extension');
         if(!$ext) die("extension plugin not available, can't continue");
+
         $plugin->setExtension($ext);
 
         $url = $plugin->getDownloadURL();
@@ -297,6 +298,7 @@ class GitToolCLI extends DokuCLI {
         /** @var helper_plugin_extension_extension $ext */
         $ext = plugin_load('helper', 'extension_extension');
         if(!$ext) die("extension plugin not available, can't continue");
+
         $ext->setExtension($extension);
 
         $repourl = $ext->getSourcerepoURL();
diff --git a/inc/Tar.class.php b/inc/Tar.class.php
index 04246846e..0dc7dace2 100644
--- a/inc/Tar.class.php
+++ b/inc/Tar.class.php
@@ -53,6 +53,7 @@ class Tar {
 
     protected $file = '';
     protected $comptype = Tar::COMPRESS_AUTO;
+    /** @var  resource|int */
     protected $fh;
     protected $memory = '';
     protected $closed = true;
@@ -530,7 +531,7 @@ class Tar {
      * Decode the given tar file header
      *
      * @param string $block a 512 byte block containign the header data
-     * @return array|false
+     * @return false|array
      */
     protected function parseHeader($block) {
         if(!$block || strlen($block) != 512) return false;
@@ -633,8 +634,14 @@ class Tar {
     }
 }
 
+/**
+ * Class TarIOException
+ */
 class TarIOException extends Exception {
 }
 
+/**
+ * Class TarIllegalCompressionException
+ */
 class TarIllegalCompressionException extends Exception {
 }
diff --git a/inc/ZipLib.class.php b/inc/ZipLib.class.php
index 0b7bfa05e..5b524c4ab 100644
--- a/inc/ZipLib.class.php
+++ b/inc/ZipLib.class.php
@@ -142,10 +142,10 @@ class ZipLib {
      *
      * @param string $data
      * @param string $name filename
-     * @param int $compact
+     * @param bool $compact
      * @return bool
      */
-    function add_File($data, $name, $compact = 1) {
+    function add_File($data, $name, $compact = true) {
         $name     = str_replace('\\', '/', $name);
         $dtime    = dechex($this->DosTime());
 
diff --git a/inc/auth.php b/inc/auth.php
index 3a6a2f65a..0342de7be 100644
--- a/inc/auth.php
+++ b/inc/auth.php
@@ -283,7 +283,7 @@ function auth_login($user, $pass, $sticky = false, $silent = false) {
  * @author Andreas Gohr <andi@splitbrain.org>
  *
  * @param  string $token The authentication token
- * @return boolean true (or will exit on failure)
+ * @return boolean|null true (or will exit on failure)
  */
 function auth_validateToken($token) {
     if(!$token || $token != $_SESSION[DOKU_COOKIE]['auth']['token']) {
diff --git a/inc/common.php b/inc/common.php
index 7932fc9f0..d628ab6b2 100644
--- a/inc/common.php
+++ b/inc/common.php
@@ -1461,7 +1461,7 @@ function dformat($dt = null, $format = '') {
  * @author <ungu at terong dot com>
  * @link http://www.php.net/manual/en/function.date.php#54072
  *
- * @param int $int_date: current date in UNIX timestamp
+ * @param int $int_date current date in UNIX timestamp
  * @return string
  */
 function date_iso8601($int_date) {
diff --git a/inc/events.php b/inc/events.php
index 4cd06b9f9..256fb561e 100644
--- a/inc/events.php
+++ b/inc/events.php
@@ -27,6 +27,9 @@ class Doku_Event {
 
     /**
      * event constructor
+     *
+     * @param string $name
+     * @param mixed $data
      */
     function Doku_Event($name, &$data) {
 
@@ -120,14 +123,18 @@ class Doku_Event {
      * stop any further processing of the event by event handlers
      * this function does not prevent the default action taking place
      */
-    function stopPropagation() { $this->_continue = false;  }
+    function stopPropagation() {
+        $this->_continue = false;
+    }
 
     /**
      * preventDefault
      *
      * prevent the default action taking place
      */
-    function preventDefault() { $this->_default = false;  }
+    function preventDefault() {
+        $this->_default = false;
+    }
 }
 
 /**
diff --git a/inc/parserutils.php b/inc/parserutils.php
index ef62c8e49..4371f1928 100644
--- a/inc/parserutils.php
+++ b/inc/parserutils.php
@@ -655,7 +655,7 @@ function p_render($mode,$instructions,&$info){
  * Figure out the correct renderer class to use for $mode,
  * instantiate and return it
  *
- * @param $mode string Mode of the renderer to get
+ * @param string $mode Mode of the renderer to get
  * @return null|Doku_Renderer The renderer
  *
  * @author Christopher Smith <chris@jalakai.co.uk>
diff --git a/inc/plugin.php b/inc/plugin.php
index 8432b21b2..3bab560cb 100644
--- a/inc/plugin.php
+++ b/inc/plugin.php
@@ -60,7 +60,7 @@ class DokuWiki_Plugin {
      * @return string  plugin name
      */
     function getPluginName() {
-        list($t, $p, $n) = explode('_', get_class($this), 4);
+        list(/* $t */, /* $p */, $n) = explode('_', get_class($this), 4);
         return $n;
     }
 
@@ -68,7 +68,7 @@ class DokuWiki_Plugin {
      * @return string  component name
      */
     function getPluginComponent() {
-        list($t, $p, $n, $c) = explode('_', get_class($this), 4);
+        list(/* $t */, /* $p */, /* $n */, $c) = explode('_', get_class($this), 4);
         return (isset($c)?$c:'');
     }
 
diff --git a/inc/template.php b/inc/template.php
index 98ea9df82..6bb6275f3 100644
--- a/inc/template.php
+++ b/inc/template.php
@@ -1066,8 +1066,8 @@ function tpl_pagetitle($id = null, $ret = false) {
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  *
- * @param array  $tags tags to try
- * @param string $alt alternative output if no data was found
+ * @param array|string $tags tags to try
+ * @param string       $alt  alternative output if no data was found
  * @param null|string   $src the image src, uses global $SRC if not given
  * @return string
  */
diff --git a/inc/utf8.php b/inc/utf8.php
index b3f2b5fe8..f86217686 100644
--- a/inc/utf8.php
+++ b/inc/utf8.php
@@ -611,7 +611,7 @@ if(!function_exists('utf8_decode_numeric')){
      * Decodes numeric HTML entities to their correct UTF-8 characters
      *
      * @param $ent string A numeric entity
-     * @return string
+     * @return string|false
      */
     function utf8_decode_numeric($ent) {
         switch ($ent[2]) {
@@ -657,7 +657,7 @@ if(!class_exists('utf8_entity_decoder')){
          * Decodes any HTML entity to it's correct UTF-8 char equivalent
          *
          * @param string $ent An entity
-         * @return string
+         * @return string|false
          */
         function decode($ent) {
             if ($ent[1] == '#') {
diff --git a/lib/exe/xmlrpc.php b/lib/exe/xmlrpc.php
index 3a878ebe4..61a68281f 100644
--- a/lib/exe/xmlrpc.php
+++ b/lib/exe/xmlrpc.php
@@ -23,6 +23,11 @@ class dokuwiki_xmlrpc_server extends IXR_Server {
         $this->IXR_Server();
     }
 
+    /**
+     * @param string $methodname
+     * @param array $args
+     * @return IXR_Error|mixed
+     */
     function call($methodname, $args){
         try {
             $result = $this->remote->call($methodname, $args);
diff --git a/lib/plugins/admin.php b/lib/plugins/admin.php
index 9a1fb9fdc..d063af612 100644
--- a/lib/plugins/admin.php
+++ b/lib/plugins/admin.php
@@ -14,6 +14,10 @@ if(!defined('DOKU_INC')) die();
  */
 class DokuWiki_Admin_Plugin extends DokuWiki_Plugin {
 
+    /**
+     * @param string $language language code
+     * @return string
+     */
     function getMenuText($language) {
         $menutext = $this->getLang('menu');
         if (!$menutext) {
@@ -23,10 +27,14 @@ class DokuWiki_Admin_Plugin extends DokuWiki_Plugin {
         return $menutext;
     }
 
+    /**
+     * @return int
+     */
     function getMenuSort() {
         return 1000;
     }
 
+
     function handle() {
         trigger_error('handle() not implemented in '.get_class($this), E_USER_WARNING);
     }
@@ -35,10 +43,16 @@ class DokuWiki_Admin_Plugin extends DokuWiki_Plugin {
         trigger_error('html() not implemented in '.get_class($this), E_USER_WARNING);
     }
 
+    /**
+     * @return bool
+     */
     function forAdminOnly() {
         return true;
     }
 
+    /**
+     * @return array
+     */
     function getTOC(){
         return array();
     }
diff --git a/lib/plugins/authplain/_test/escaping.test.php b/lib/plugins/authplain/_test/escaping.test.php
index cd5294157..5cf631508 100644
--- a/lib/plugins/authplain/_test/escaping.test.php
+++ b/lib/plugins/authplain/_test/escaping.test.php
@@ -12,10 +12,11 @@
  * @group plugins
  */
 class helper_plugin_authplain_escaping_test extends DokuWikiTest {
- 
+
     protected $pluginsEnabled = array('authplain');
+    /** @var  auth_plugin_authplain */
     protected $auth;
- 
+
     protected function reloadUsers() {
         /* auth caches data loaded from file, but recreated object forces reload */
         $this->auth = new auth_plugin_authplain();
diff --git a/lib/plugins/config/settings/config.class.php b/lib/plugins/config/settings/config.class.php
index cbf6ea452..590631dae 100644
--- a/lib/plugins/config/settings/config.class.php
+++ b/lib/plugins/config/settings/config.class.php
@@ -570,7 +570,7 @@ if (!class_exists('setting')) {
         /**
          * Returns caution
          *
-         * @return bool|string caution string, otherwise false for invalid caution
+         * @return false|string caution string, otherwise false for invalid caution
          */
         public function caution() {
             if (!empty($this->_caution)) {
diff --git a/lib/plugins/extension/admin.php b/lib/plugins/extension/admin.php
index 99c74848b..de4992937 100644
--- a/lib/plugins/extension/admin.php
+++ b/lib/plugins/extension/admin.php
@@ -75,10 +75,10 @@ class admin_plugin_extension extends DokuWiki_Admin_Plugin {
                             case 'uninstall':
                                 $extension->setExtension($extname);
                                 $status = $extension->uninstall();
-                                if($status !== true) {
-                                    msg($status, -1);
-                                } else {
+                                if($status) {
                                     msg(sprintf($this->getLang('msg_delete_success'), hsc($extension->getDisplayName())), 1);
+                                } else {
+                                    msg(sprintf($this->getLang('msg_delete_failed'), hsc($extension->getDisplayName())), -1);
                                 }
                                 break;
                             case 'enable';
diff --git a/lib/plugins/extension/helper/repository.php b/lib/plugins/extension/helper/repository.php
index 6ffe89eb7..5dc2707cf 100644
--- a/lib/plugins/extension/helper/repository.php
+++ b/lib/plugins/extension/helper/repository.php
@@ -32,7 +32,7 @@ class helper_plugin_extension_repository extends DokuWiki_Plugin {
             $request_needed = false;
             foreach ($list as $name) {
                 $cache = new cache('##extension_manager##'.$name, '.repo');
-                $result = null;
+
                 if (!isset($this->loaded_extensions[$name]) && $this->hasAccess() && !$cache->useCache(array('age' => 3600 * 24))) {
                     $this->loaded_extensions[$name] = true;
                     $request_data['ext'][] = $name;
@@ -64,7 +64,7 @@ class helper_plugin_extension_repository extends DokuWiki_Plugin {
     public function hasAccess() {
         if ($this->has_access === null) {
             $cache = new cache('##extension_manager###hasAccess', '.repo');
-            $result = null;
+
             if (!$cache->useCache(array('age' => 3600 * 24, 'purge'=>1))) {
                 $httpclient = new DokuHTTPClient();
                 $httpclient->timeout = 5;
@@ -91,7 +91,7 @@ class helper_plugin_extension_repository extends DokuWiki_Plugin {
      */
     public function getData($name) {
         $cache = new cache('##extension_manager##'.$name, '.repo');
-        $result = null;
+
         if (!isset($this->loaded_extensions[$name]) && $this->hasAccess() && !$cache->useCache(array('age' => 3600 * 24))) {
             $this->loaded_extensions[$name] = true;
             $httpclient = new DokuHTTPClient();
diff --git a/lib/plugins/extension/lang/en/lang.php b/lib/plugins/extension/lang/en/lang.php
index 72c9b9e2d..4da41a2fd 100644
--- a/lib/plugins/extension/lang/en/lang.php
+++ b/lib/plugins/extension/lang/en/lang.php
@@ -69,7 +69,8 @@ $lang['status_bundled']               = 'bundled';
 
 $lang['msg_enabled']                  = 'Plugin %s enabled';
 $lang['msg_disabled']                 = 'Plugin %s disabled';
-$lang['msg_delete_success']           = 'Extension uninstalled';
+$lang['msg_delete_success']           = 'Extension %s uninstalled';
+$lang['msg_delete_failed']            = 'Uninstalling Extension %s failed';
 $lang['msg_template_install_success'] = 'Template %s installed successfully';
 $lang['msg_template_update_success']  = 'Template %s updated successfully';
 $lang['msg_plugin_install_success']   = 'Plugin %s installed successfully';
diff --git a/lib/plugins/extension/lang/nl/lang.php b/lib/plugins/extension/lang/nl/lang.php
index a54924e93..f75f78121 100644
--- a/lib/plugins/extension/lang/nl/lang.php
+++ b/lib/plugins/extension/lang/nl/lang.php
@@ -63,7 +63,7 @@ $lang['status_template']       = 'template';
 $lang['status_bundled']        = 'Gebundeld';
 $lang['msg_enabled']           = 'Plugin %s ingeschakeld';
 $lang['msg_disabled']          = 'Plugin %s uitgeschakeld';
-$lang['msg_delete_success']    = 'Uitbreiding gedeinstalleerd';
+$lang['msg_delete_success']    = 'Uitbreiding %s gedeinstalleerd';
 $lang['msg_template_install_success'] = 'Template %s werd succesvol geïnstalleerd';
 $lang['msg_template_update_success'] = 'Template %s werd succesvol geüpdatet';
 $lang['msg_plugin_install_success'] = 'Plugin %s werd succesvol geïnstalleerd';