From 7e8500eea1e53b1de0e0f70400664afa442cd08d Mon Sep 17 00:00:00 2001
From: Gerrit Uitslag <klapinklapin@gmail.com>
Date: Thu, 2 Oct 2014 14:55:24 +0200
Subject: [PATCH] PHPDocs and some improvements
---
bin/gittool.php | 4 +++-
inc/Tar.class.php | 9 ++++++++-
inc/ZipLib.class.php | 4 ++--
inc/auth.php | 2 +-
inc/common.php | 2 +-
inc/events.php | 11 +++++++++--
inc/parserutils.php | 2 +-
inc/plugin.php | 4 ++--
inc/template.php | 4 ++--
inc/utf8.php | 4 ++--
lib/exe/xmlrpc.php | 5 +++++
lib/plugins/admin.php | 14 ++++++++++++++
lib/plugins/authplain/_test/escaping.test.php | 5 +++--
lib/plugins/config/settings/config.class.php | 2 +-
lib/plugins/extension/admin.php | 6 +++---
lib/plugins/extension/helper/repository.php | 6 +++---
lib/plugins/extension/lang/en/lang.php | 3 ++-
lib/plugins/extension/lang/nl/lang.php | 2 +-
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';
--
GitLab