diff --git a/inc/EmailAddressValidator.php b/inc/EmailAddressValidator.php
index bb4ef0ca9f151452b98a633c3bd226c1a2334a3a..fd6f3275babd7d144a13ecfcc21a6e00b535221d 100644
--- a/inc/EmailAddressValidator.php
+++ b/inc/EmailAddressValidator.php
@@ -15,8 +15,8 @@ class EmailAddressValidator {
/**
* Check email address validity
- * @param strEmailAddress Email address to be checked
- * @return True if email is valid, false if not
+ * @param string $strEmailAddress Email address to be checked
+ * @return bool True if email is valid, false if not
*/
public function check_email_address($strEmailAddress) {
@@ -82,8 +82,8 @@ class EmailAddressValidator {
/**
* Checks email section before "@" symbol for validity
- * @param strLocalPortion Text to be checked
- * @return True if local portion is valid, false if not
+ * @param string $strLocalPortion Text to be checked
+ * @return bool True if local portion is valid, false if not
*/
protected function check_local_portion($strLocalPortion) {
// Local portion can only be from 1 to 64 characters, inclusive.
@@ -113,8 +113,8 @@ class EmailAddressValidator {
/**
* Checks email section after "@" symbol for validity
- * @param strDomainPortion Text to be checked
- * @return True if domain portion is valid, false if not
+ * @param string $strDomainPortion Text to be checked
+ * @return bool True if domain portion is valid, false if not
*/
protected function check_domain_portion($strDomainPortion) {
// Total domain can only be from 1 to 255 characters, inclusive
@@ -172,10 +172,10 @@ class EmailAddressValidator {
/**
* Check given text length is between defined bounds
- * @param strText Text to be checked
- * @param intMinimum Minimum acceptable length
- * @param intMaximum Maximum acceptable length
- * @return True if string is within bounds (inclusive), false if not
+ * @param string $strText Text to be checked
+ * @param int $intMinimum Minimum acceptable length
+ * @param int $intMaximum Maximum acceptable length
+ * @return bool True if string is within bounds (inclusive), false if not
*/
protected function check_text_length($strText, $intMinimum, $intMaximum) {
// Minimum and maximum are both inclusive
diff --git a/inc/cache.php b/inc/cache.php
index 5eac949345808328231dca38938410a9358c468d..5f54a34a94b7f70b67d1705229dfca45cdc9125f 100644
--- a/inc/cache.php
+++ b/inc/cache.php
@@ -8,16 +8,24 @@
if(!defined('DOKU_INC')) die('meh.');
+/**
+ * Generic handling of caching
+ */
class cache {
- var $key = ''; // primary identifier for this item
- var $ext = ''; // file ext for cache data, secondary identifier for this item
- var $cache = ''; // cache file name
- var $depends = array(); // array containing cache dependency information,
+ public $key = ''; // primary identifier for this item
+ public $ext = ''; // file ext for cache data, secondary identifier for this item
+ public $cache = ''; // cache file name
+ public $depends = array(); // array containing cache dependency information,
// used by _useCache to determine cache validity
var $_event = ''; // event to be triggered during useCache
+ var $_time;
- function cache($key,$ext) {
+ /**
+ * @param string $key primary identifier
+ * @param string $ext file extension
+ */
+ public function cache($key,$ext) {
$this->key = $key;
$this->ext = $ext;
$this->cache = getCacheName($key,$ext);
@@ -36,7 +44,7 @@ class cache {
*
* @return bool true if cache can be used, false otherwise
*/
- function useCache($depends=array()) {
+ public function useCache($depends=array()) {
$this->depends = $depends;
$this->_addDependencies();
@@ -59,7 +67,7 @@ class cache {
*
* @return bool see useCache()
*/
- function _useCache() {
+ protected function _useCache() {
if (!empty($this->depends['purge'])) return false; // purge requested?
if (!($this->_time = @filemtime($this->cache))) return false; // cache exists?
@@ -83,7 +91,7 @@ class cache {
* it should not remove any existing dependencies and
* it should only overwrite a dependency when the new value is more stringent than the old
*/
- function _addDependencies() {
+ protected function _addDependencies() {
global $INPUT;
if ($INPUT->has('purge')) $this->depends['purge'] = true; // purge requested
}
@@ -94,7 +102,7 @@ class cache {
* @param bool $clean true to clean line endings, false to leave line endings alone
* @return string cache contents
*/
- function retrieveCache($clean=true) {
+ public function retrieveCache($clean=true) {
return io_readFile($this->cache, $clean);
}
@@ -104,14 +112,14 @@ class cache {
* @param string $data the data to be cached
* @return bool true on success, false otherwise
*/
- function storeCache($data) {
+ public function storeCache($data) {
return io_savefile($this->cache, $data);
}
/**
* remove any cached data associated with this cache instance
*/
- function removeCache() {
+ public function removeCache() {
@unlink($this->cache);
}
@@ -122,7 +130,7 @@ class cache {
* @param bool $success result of this cache use attempt
* @return bool pass-thru $success value
*/
- function _stats($success) {
+ protected function _stats($success) {
global $conf;
static $stats = null;
static $file;
@@ -157,14 +165,23 @@ class cache {
}
}
+/**
+ * Parser caching
+ */
class cache_parser extends cache {
- var $file = ''; // source file for cache
- var $mode = ''; // input mode (represents the processing the input file will undergo)
+ public $file = ''; // source file for cache
+ public $mode = ''; // input mode (represents the processing the input file will undergo)
var $_event = 'PARSER_CACHE_USE';
- function cache_parser($id, $file, $mode) {
+ /**
+ *
+ * @param string $id page id
+ * @param string $file source file for cache
+ * @param string $mode input mode
+ */
+ public function cache_parser($id, $file, $mode) {
if ($id) $this->page = $id;
$this->file = $file;
$this->mode = $mode;
@@ -172,24 +189,29 @@ class cache_parser extends cache {
parent::cache($file.$_SERVER['HTTP_HOST'].$_SERVER['SERVER_PORT'],'.'.$mode);
}
- function _useCache() {
+ /**
+ * method contains cache use decision logic
+ *
+ * @return bool see useCache()
+ */
+ protected function _useCache() {
if (!@file_exists($this->file)) return false; // source exists?
return parent::_useCache();
}
- function _addDependencies() {
- global $conf, $config_cascade;
+ protected function _addDependencies() {
+ global $conf;
$this->depends['age'] = isset($this->depends['age']) ?
min($this->depends['age'],$conf['cachetime']) : $conf['cachetime'];
// parser cache file dependencies ...
- $files = array($this->file, // ... source
+ $files = array($this->file, // ... source
DOKU_INC.'inc/parser/parser.php', // ... parser
DOKU_INC.'inc/parser/handler.php', // ... handler
);
- $files = array_merge($files, getConfigFiles('main')); // ... wiki settings
+ $files = array_merge($files, getConfigFiles('main')); // ... wiki settings
$this->depends['files'] = !empty($this->depends['files']) ? array_merge($files, $this->depends['files']) : $files;
parent::_addDependencies();
@@ -197,8 +219,17 @@ class cache_parser extends cache {
}
+/**
+ * Caching of data of renderer
+ */
class cache_renderer extends cache_parser {
- function _useCache() {
+
+ /**
+ * method contains cache use decision logic
+ *
+ * @return bool see useCache()
+ */
+ protected function _useCache() {
global $conf;
if (!parent::_useCache()) return false;
@@ -231,7 +262,7 @@ class cache_renderer extends cache_parser {
return true;
}
- function _addDependencies() {
+ protected function _addDependencies() {
// renderer cache file dependencies ...
$files = array(
@@ -253,18 +284,37 @@ class cache_renderer extends cache_parser {
}
}
+/**
+ * Caching of parser instructions
+ */
class cache_instructions extends cache_parser {
- function cache_instructions($id, $file) {
+ /**
+ * @param string $id page id
+ * @param string $file source file for cache
+ */
+ public function cache_instructions($id, $file) {
parent::cache_parser($id, $file, 'i');
}
- function retrieveCache($clean=true) {
+ /**
+ * retrieve the cached data
+ *
+ * @param bool $clean true to clean line endings, false to leave line endings alone
+ * @return string cache contents
+ */
+ public function retrieveCache($clean=true) {
$contents = io_readFile($this->cache, false);
return !empty($contents) ? unserialize($contents) : array();
}
- function storeCache($instructions) {
+ /**
+ * cache $instructions
+ *
+ * @param string $instructions the instruction to be cached
+ * @return bool true on success, false otherwise
+ */
+ public function storeCache($instructions) {
return io_savefile($this->cache,serialize($instructions));
}
}
diff --git a/inc/common.php b/inc/common.php
index bbc0a6e6810c26736e5dea03eb853a94082ff8a7..9a53ee52627c76b1b1f1598a076af302d5e7bdc0 100644
--- a/inc/common.php
+++ b/inc/common.php
@@ -1141,7 +1141,6 @@ function saveWikiText($id, $text, $summary, $minor = false) {
* @author Andreas Gohr <andi@splitbrain.org>
*/
function saveOldRevision($id) {
- global $conf;
$oldf = wikiFN($id);
if(!@file_exists($oldf)) return '';
$date = filemtime($oldf);
@@ -1231,8 +1230,9 @@ function getGoogleQuery() {
/**
* Return the human readable size of a file
*
- * @param int $size A file size
- * @param int $dec A number of decimal places
+ * @param int $size A file size
+ * @param int $dec A number of decimal places
+ * @return string human readable size
* @author Martin Benjamin <b.martin@cybernet.ch>
* @author Aidan Lister <aidan@php.net>
* @version 1.0.0
@@ -1363,12 +1363,16 @@ function php_to_byte($v) {
$l = substr($v, -1);
$ret = substr($v, 0, -1);
switch(strtoupper($l)) {
+ /** @noinspection PhpMissingBreakStatementInspection */
case 'P':
$ret *= 1024;
+ /** @noinspection PhpMissingBreakStatementInspection */
case 'T':
$ret *= 1024;
+ /** @noinspection PhpMissingBreakStatementInspection */
case 'G':
$ret *= 1024;
+ /** @noinspection PhpMissingBreakStatementInspection */
case 'M':
$ret *= 1024;
case 'K':
diff --git a/inc/events.php b/inc/events.php
index 58ba4d5e4a7f05cde53ace758649733c25f304ce..7f9824f605a67c592a596f1d0a57748768f218a6 100644
--- a/inc/events.php
+++ b/inc/events.php
@@ -8,6 +8,9 @@
if(!defined('DOKU_INC')) die('meh.');
+/**
+ * The event
+ */
class Doku_Event {
// public properties
@@ -32,6 +35,9 @@ class Doku_Event {
}
+ /**
+ * @return string
+ */
function __toString() {
return $this->name;
}
@@ -51,7 +57,8 @@ class Doku_Event {
* $evt->advise_after();
* unset($evt);
*
- * @return results of processing the event, usually $this->_default
+ * @param bool $enablePreventDefault
+ * @return bool results of processing the event, usually $this->_default
*/
function advise_before($enablePreventDefault=true) {
global $EVENT_HANDLER;
@@ -77,7 +84,9 @@ class Doku_Event {
* $this->_default, all of which may have been modified by the event handlers.
* - advise all registered (<event>_AFTER) handlers that the event has taken place
*
- * @return $event->results
+ * @param null|callable $action
+ * @param bool $enablePrevent
+ * @return mixed $event->results
* the value set by any <event>_before or <event> handlers if the default action is prevented
* or the results of the default action (as modified by <event>_after handlers)
* or NULL no action took place and no handler modified the value
@@ -116,6 +125,9 @@ class Doku_Event {
function preventDefault() { $this->_default = false; }
}
+/**
+ * Controls the registration and execution of all events,
+ */
class Doku_Event_Handler {
// public properties: none
@@ -132,6 +144,7 @@ class Doku_Event_Handler {
function Doku_Event_Handler() {
// load action plugins
+ /** @var DokuWiki_Action_Plugin $plugin */
$plugin = null;
$pluginlist = plugin_list('action');
@@ -147,12 +160,13 @@ class Doku_Event_Handler {
*
* register a hook for an event
*
- * @param $event (string) name used by the event, (incl '_before' or '_after' for triggers)
- * @param $obj (obj) object in whose scope method is to be executed,
+ * @param $event string name used by the event, (incl '_before' or '_after' for triggers)
+ * @param $advise string
+ * @param $obj object object in whose scope method is to be executed,
* if NULL, method is assumed to be a globally available function
- * @param $method (function) event handler function
- * @param $param (mixed) data passed to the event handler
- * @param $seq (int) sequence number for ordering hook execution (ascending)
+ * @param $method string event handler function
+ * @param $param mixed data passed to the event handler
+ * @param $seq int sequence number for ordering hook execution (ascending)
*/
function register_hook($event, $advise, $obj, $method, $param=null, $seq=0) {
$seq = (int)$seq;
@@ -164,6 +178,12 @@ class Doku_Event_Handler {
}
}
+ /**
+ * process the before/after event
+ *
+ * @param Doku_Event $event
+ * @param string $advise BEFORE or AFTER
+ */
function process_event($event,$advise='') {
$evt_name = $event->name . ($advise ? '_'.$advise : '_BEFORE');
@@ -191,12 +211,12 @@ class Doku_Event_Handler {
*
* function wrapper to process (create, trigger and destroy) an event
*
- * @param $name (string) name for the event
- * @param $data (mixed) event data
- * @param $action (callback) (optional, default=NULL) default action, a php callback function
- * @param $canPreventDefault (bool) (optional, default=true) can hooks prevent the default action
+ * @param $name string name for the event
+ * @param $data mixed event data
+ * @param $action callback (optional, default=NULL) default action, a php callback function
+ * @param $canPreventDefault bool (optional, default=true) can hooks prevent the default action
*
- * @return (mixed) the event results value after all event processing is complete
+ * @return mixed the event results value after all event processing is complete
* by default this is the return value of the default action however
* it can be set or modified by event handler hooks
*/
diff --git a/inc/form.php b/inc/form.php
index 312c42b6078a5f91aa83eb9917ae91a01bde1b30..610f5020074a56fc2e1e24b910d56a7622a14670 100644
--- a/inc/form.php
+++ b/inc/form.php
@@ -47,15 +47,11 @@ class Doku_Form {
* with up to four parameters is deprecated, instead the first parameter
* should be an array with parameters.
*
- * @param mixed $params Parameters for the HTML form element; Using the
- * deprecated calling convention this is the ID
- * attribute of the form
- * @param string $action (optional, deprecated) submit URL, defaults to
- * current page
- * @param string $method (optional, deprecated) 'POST' or 'GET', default
- * is POST
- * @param string $enctype (optional, deprecated) Encoding type of the
- * data
+ * @param mixed $params Parameters for the HTML form element; Using the deprecated
+ * calling convention this is the ID attribute of the form
+ * @param bool|string $action (optional, deprecated) submit URL, defaults to current page
+ * @param bool|string $method (optional, deprecated) 'POST' or 'GET', default is POST
+ * @param bool|string $enctype (optional, deprecated) Encoding type of the data
* @author Tom N Harris <tnharris@whoopdedo.org>
*/
function Doku_Form($params, $action=false, $method=false, $enctype=false) {
@@ -230,7 +226,7 @@ class Doku_Form {
* first (underflow) or last (overflow) element.
*
* @param int $pos 0-based index
- * @return arrayreference pseudo-element
+ * @return array reference pseudo-element
* @author Tom N Harris <tnharris@whoopdedo.org>
*/
function &getElementAt($pos) {
diff --git a/inc/pageutils.php b/inc/pageutils.php
index c8d3cf4bb506ce7e33f0a829ca7b1e80a9dbe53d..9c2794387882840beaadde79b2c481c952feec1d 100644
--- a/inc/pageutils.php
+++ b/inc/pageutils.php
@@ -94,6 +94,7 @@ function getID($param='id',$clean=true){
* @author Andreas Gohr <andi@splitbrain.org>
* @param string $raw_id The pageid to clean
* @param boolean $ascii Force ASCII
+ * @return string cleaned id
*/
function cleanID($raw_id,$ascii=false){
global $conf;
@@ -244,6 +245,7 @@ function page_exists($id,$rev='',$clean=true) {
* @param $rev string page revision, empty string for current
* @param $clean bool flag indicating that $raw_id should be cleaned. Only set to false
* when $id is guaranteed to have been cleaned already.
+ * @return string full path
*
* @author Andreas Gohr <andi@splitbrain.org>
*/
@@ -361,6 +363,7 @@ function mediaFN($id, $rev=''){
*
* @param string $id The id of the local file
* @param string $ext The file extension (usually txt)
+ * @return string full filepath to localized file
* @author Andreas Gohr <andi@splitbrain.org>
*/
function localeFN($id,$ext='txt'){
@@ -543,6 +546,11 @@ function isHiddenPage($id){
return $data['hidden'];
}
+/**
+ * callback checks if page is hidden
+ *
+ * @param array $data event data see isHiddenPage()
+ */
function _isHiddenPage(&$data) {
global $conf;
global $ACT;
diff --git a/inc/pluginutils.php b/inc/pluginutils.php
index 894bbefb6c7512effc89cc86a3b62e574326866f..911c4e5c0811076aa250ba93ef30c46f69ac9761 100644
--- a/inc/pluginutils.php
+++ b/inc/pluginutils.php
@@ -37,7 +37,7 @@ function plugin_list($type='',$all=false) {
* @param $name string name of the plugin to load
* @param $new bool true to return a new instance of the plugin, false to use an already loaded instance
* @param $disabled bool true to load even disabled plugins
- * @return DokuWiki_Plugin|DokuWiki_Syntax_Plugin|null the plugin object or null on failure
+ * @return DokuWiki_Plugin|null the plugin object or null on failure
*/
function plugin_load($type,$name,$new=false,$disabled=false) {
/** @var $plugin_controller Doku_Plugin_Controller */
diff --git a/lib/exe/js.php b/lib/exe/js.php
index 04413b40966225906bcea14a8e44c94d177d3495..8f16f4a9623294c470bf32f595c430f309ab203c 100644
--- a/lib/exe/js.php
+++ b/lib/exe/js.php
@@ -220,6 +220,12 @@ function js_pluginstrings() {
return $pluginstrings;
}
+/**
+ * Return an two-dimensional array with strings from the language file of current active template.
+ *
+ * - $lang['js'] must be an array.
+ * - Nothing is returned for template without an entry for $lang['js']
+ */
function js_templatestrings() {
global $conf;
$templatestrings = array();