From 42ea7f447f39fbc2f79eaaec31f8c10ede59c5d0 Mon Sep 17 00:00:00 2001 From: Gerrit Uitslag Date: Wed, 1 Oct 2014 11:30:27 +0200 Subject: Many PHPDocs, some unused and dyn declared vars many PHPDocs some unused variables some dynamically declared variables declared --- bin/gittool.php | 6 +- bin/wantedpages.php | 20 ++++ inc/DifferenceEngine.php | 80 ++++++++++--- inc/HTTPClient.php | 39 ++++-- inc/IXR_Library.php | 11 ++ inc/Input.class.php | 7 +- inc/JpegMeta.php | 76 +++++++++++- inc/Mailer.class.php | 21 +++- inc/PassHash.class.php | 23 ++-- inc/RemoteAPICore.php | 135 ++++++++++++++++++++- inc/Sitemapper.php | 18 ++- inc/Tar.class.php | 14 ++- inc/actions.php | 45 ++++++- inc/auth.php | 27 ++++- inc/blowfish.php | 15 +-- inc/changelog.php | 6 +- inc/cli.php | 23 ++-- inc/common.php | 17 +-- inc/confutils.php | 4 + inc/events.php | 24 ++-- inc/fetch.functions.php | 7 +- inc/form.php | 98 ++++++++++++++- inc/fulltext.php | 47 ++++++++ inc/html.php | 68 ++++++++++- inc/httputils.php | 11 ++ inc/indexer.php | 69 ++++++++++- inc/io.php | 71 ++++++++++- inc/media.php | 264 +++++++++++++++++++++++++++++------------ inc/pageutils.php | 8 +- inc/parser/handler.php | 5 +- inc/parser/renderer.php | 10 +- inc/parser/xhtml.php | 13 +- inc/parserutils.php | 49 +++++++- inc/plugin.php | 45 +++++-- inc/plugincontroller.class.php | 17 ++- inc/remote.php | 105 +++++++++++++++- inc/search.php | 5 + inc/subscription.php | 3 +- inc/template.php | 59 +++++++-- lib/exe/xmlrpc.php | 8 ++ lib/plugins/acl/remote.php | 30 ++++- 41 files changed, 1354 insertions(+), 249 deletions(-) diff --git a/bin/gittool.php b/bin/gittool.php index 6944dde57..7991a9997 100755 --- a/bin/gittool.php +++ b/bin/gittool.php @@ -101,7 +101,7 @@ class GitToolCLI extends DokuCLI { /** * Tries to install the given extensions using git clone * - * @param $extensions + * @param array $extensions */ public function cmd_clone($extensions) { $errors = array(); @@ -130,7 +130,7 @@ class GitToolCLI extends DokuCLI { /** * Tries to install the given extensions using git clone with fallback to install * - * @param $extensions + * @param array $extensions */ public function cmd_install($extensions) { $errors = array(); @@ -291,7 +291,7 @@ class GitToolCLI extends DokuCLI { * Returns the repository for the given extension * * @param $extension - * @return bool|string + * @return false|string */ private function getSourceRepo($extension) { /** @var helper_plugin_extension_extension $ext */ diff --git a/bin/wantedpages.php b/bin/wantedpages.php index 8fc4ba74f..54bfd4755 100755 --- a/bin/wantedpages.php +++ b/bin/wantedpages.php @@ -61,6 +61,13 @@ class WantedPagesCLI extends DokuCLI { } } + /** + * Determine directions of the search loop + * + * @param string $entry + * @param string $basepath + * @return int + */ protected function dir_filter($entry, $basepath) { if($entry == '.' || $entry == '..') { return WantedPagesCLI::DIR_CONTINUE; @@ -77,6 +84,13 @@ class WantedPagesCLI extends DokuCLI { return WantedPagesCLI::DIR_CONTINUE; } + /** + * Collects recursively the pages in a namespace + * + * @param string $dir + * @return array + * @throws DokuCLI_Exception + */ protected function get_pages($dir) { static $trunclen = null; if(!$trunclen) { @@ -108,6 +122,12 @@ class WantedPagesCLI extends DokuCLI { return $pages; } + /** + * Parse instructions and returns the non-existing links + * + * @param array $page array with page id and file path + * @return array + */ function internal_links($page) { global $conf; $instructions = p_get_instructions(file_get_contents($page['file'])); diff --git a/inc/DifferenceEngine.php b/inc/DifferenceEngine.php index 3c955cf88..210d1c0eb 100644 --- a/inc/DifferenceEngine.php +++ b/inc/DifferenceEngine.php @@ -14,6 +14,9 @@ class _DiffOp { var $orig; var $closing; + /** + * @return _DiffOp + */ function reverse() { trigger_error("pure virtual", E_USER_ERROR); } @@ -104,6 +107,21 @@ class _DiffOp_Change extends _DiffOp { */ class _DiffEngine { + var $xchanged = array(); + var $ychanged = array(); + var $xv = array(); + var $yv = array(); + var $xind = array(); + var $yind = array(); + var $seq; + var $in_seq; + var $lcs; + + /** + * @param array $from_lines + * @param array $to_lines + * @return _DiffOp[] + */ function diff($from_lines, $to_lines) { $n_from = count($from_lines); $n_to = count($to_lines); @@ -495,9 +513,9 @@ class Diff { * Constructor. * Computes diff between sequences of strings. * - * @param $from_lines array An array of strings. - * (Typically these are lines from a file.) - * @param $to_lines array An array of strings. + * @param array $from_lines An array of strings. + * (Typically these are lines from a file.) + * @param array $to_lines An array of strings. */ function __construct($from_lines, $to_lines) { $eng = new _DiffEngine; @@ -512,8 +530,9 @@ class Diff { * * $diff = new Diff($lines1, $lines2); * $rev = $diff->reverse(); - * @return object A Diff object representing the inverse of the - * original diff. + * + * @return Diff A Diff object representing the inverse of the + * original diff. */ function reverse() { $rev = $this; @@ -631,19 +650,19 @@ class MappedDiff extends Diff { * case-insensitve diffs, or diffs which ignore * changes in white-space. * - * @param $from_lines array An array of strings. - * (Typically these are lines from a file.) + * @param string[] $from_lines An array of strings. + * (Typically these are lines from a file.) * - * @param $to_lines array An array of strings. + * @param string[] $to_lines An array of strings. * - * @param $mapped_from_lines array This array should - * have the same size number of elements as $from_lines. - * The elements in $mapped_from_lines and - * $mapped_to_lines are what is actually compared - * when computing the diff. + * @param string[] $mapped_from_lines This array should + * have the same size number of elements as $from_lines. + * The elements in $mapped_from_lines and + * $mapped_to_lines are what is actually compared + * when computing the diff. * - * @param $mapped_to_lines array This array should - * have the same number of elements as $to_lines. + * @param string[] $mapped_to_lines This array should + * have the same number of elements as $to_lines. */ function __construct($from_lines, $to_lines, $mapped_from_lines, $mapped_to_lines) { @@ -697,12 +716,13 @@ class DiffFormatter { /** * Format a diff. * - * @param $diff object A Diff object. + * @param Diff $diff A Diff object. * @return string The formatted output. */ function format($diff) { $xi = $yi = 1; + $x0 = $y0 = 0; $block = false; $context = array(); @@ -752,6 +772,13 @@ class DiffFormatter { return $this->_end_diff(); } + /** + * @param int $xbeg + * @param int $xlen + * @param int $ybeg + * @param int $ylen + * @param array $edits + */ function _block($xbeg, $xlen, $ybeg, $ylen, &$edits) { $this->_start_block($this->_block_header($xbeg, $xlen, $ybeg, $ylen)); foreach ($edits as $edit) { @@ -779,6 +806,13 @@ class DiffFormatter { return $val; } + /** + * @param int $xbeg + * @param int $xlen + * @param int $ybeg + * @param int $ylen + * @return string + */ function _block_header($xbeg, $xlen, $ybeg, $ylen) { if ($xlen > 1) $xbeg .= "," . ($xbeg + $xlen - 1); @@ -788,6 +822,9 @@ class DiffFormatter { return $xbeg . ($xlen ? ($ylen ? 'c' : 'd') : 'a') . $ybeg; } + /** + * @param string $header + */ function _start_block($header) { echo $header; } @@ -896,6 +933,9 @@ class _HWLDF_WordAccumulator { $this->_tag = $new_tag; } + /** + * @param string $new_tag + */ function _flushLine($new_tag) { $this->_flushGroup($new_tag); if ($this->_line != '') @@ -1055,6 +1095,10 @@ class TableDiffFormatter extends DiffFormatter { $this->trailing_context_lines = 2; } + /** + * @param Diff $diff + * @return string + */ function format($diff) { // Preserve whitespaces by converting some to non-breaking spaces. // Do not convert all of them to allow word-wrap. @@ -1165,6 +1209,10 @@ class InlineDiffFormatter extends DiffFormatter { $this->trailing_context_lines = 2; } + /** + * @param Diff $diff + * @return string + */ function format($diff) { // Preserve whitespaces by converting some to non-breaking spaces. // Do not convert all of them to allow word-wrap. diff --git a/inc/HTTPClient.php b/inc/HTTPClient.php index ea20e3e56..2e991b52f 100644 --- a/inc/HTTPClient.php +++ b/inc/HTTPClient.php @@ -172,7 +172,8 @@ class HTTPClient { * * @param string $url The URL to fetch * @param bool $sloppy304 Return body on 304 not modified - * @return bool|string response body, false on error + * @return false|string response body, false on error + * * @author Andreas Gohr */ function get($url,$sloppy304=false){ @@ -193,7 +194,8 @@ class HTTPClient { * @param string $url The URL to fetch * @param array $data Associative array of parameters * @param bool $sloppy304 Return body on 304 not modified - * @return bool|string response body, false on error + * @return false|string response body, false on error + * * @author Andreas Gohr */ function dget($url,$data,$sloppy304=false){ @@ -213,7 +215,7 @@ class HTTPClient { * * @param string $url The URL to fetch * @param array $data Associative array of parameters - * @return bool|string response body, false on error + * @return false|string response body, false on error * @author Andreas Gohr */ function post($url,$data){ @@ -235,6 +237,7 @@ class HTTPClient { * @param mixed $data - the post data either as array or raw data * @param string $method - HTTP Method usually GET or POST. * @return bool - true on success + * * @author Andreas Goetz * @author Andreas Gohr */ @@ -602,6 +605,7 @@ class HTTPClient { * @param string $data The data to write * @param string $message Description of what is being read * @throws HTTPClientException + * * @author Tom N Harris */ function _sendData($socket, $data, $message) { @@ -646,6 +650,7 @@ class HTTPClient { * @param bool $ignore_eof End-of-file is not an error if this is set * @throws HTTPClientException * @return string + * * @author Tom N Harris */ function _readData($socket, $nbytes, $message, $ignore_eof = false) { @@ -695,6 +700,7 @@ class HTTPClient { * @param string $message Description of what is being read * @throws HTTPClientException * @return string + * * @author Tom N Harris */ function _readLine($socket, $message) { @@ -729,6 +735,9 @@ class HTTPClient { * Uses _debug_text or _debug_html depending on the SAPI name * * @author Andreas Gohr + * + * @param string $info + * @param mixed $var */ function _debug($info,$var=null){ if(!$this->debug) return; @@ -742,8 +751,8 @@ class HTTPClient { /** * print debug info as HTML * - * @param $info - * @param null $var + * @param string $info + * @param mixed $var */ function _debug_html($info, $var=null){ print ''.$info.' '.($this->_time() - $this->start).'s
'; @@ -759,8 +768,8 @@ class HTTPClient { /** * prints debug info as plain text * - * @param $info - * @param null $var + * @param string $info + * @param mixed $var */ function _debug_text($info, $var=null){ print '*'.$info.'* '.($this->_time() - $this->start)."s\n"; @@ -770,6 +779,8 @@ class HTTPClient { /** * Return current timestamp in microsecond resolution + * + * @return float */ static function _time(){ list($usec, $sec) = explode(" ", microtime()); @@ -782,6 +793,9 @@ class HTTPClient { * All Keys are lowercased. * * @author Andreas Gohr + * + * @param string $string + * @return array */ function _parseHeaders($string){ $headers = array(); @@ -810,6 +824,9 @@ class HTTPClient { * convert given header array to header string * * @author Andreas Gohr + * + * @param array $headers + * @return string */ function _buildHeaders($headers){ $string = ''; @@ -824,6 +841,8 @@ class HTTPClient { * get cookies as http header string * * @author Andreas Goetz + * + * @return string */ function _getCookies(){ $headers = ''; @@ -839,6 +858,9 @@ class HTTPClient { * Encode data for posting * * @author Andreas Gohr + * + * @param array $data + * @return string */ function _postEncode($data){ return http_build_query($data,'','&'); @@ -849,6 +871,9 @@ class HTTPClient { * * @fixme use of urlencode might be wrong here * @author Andreas Gohr + * + * @param array $data + * @return string */ function _postMultipartEncode($data){ $boundary = '--'.$this->boundary; diff --git a/inc/IXR_Library.php b/inc/IXR_Library.php index 2becf4a54..6ec397894 100644 --- a/inc/IXR_Library.php +++ b/inc/IXR_Library.php @@ -140,6 +140,10 @@ class IXR_Message { var $_lastseen; // The XML parser var $_parser; + + /** + * @param string $message + */ function IXR_Message ($message) { $this->message = $message; } @@ -684,6 +688,13 @@ class IXR_IntrospectionServer extends IXR_Server { 'Returns a documentation string for the specified method' ); } + + /** + * @param string $method + * @param string $callback + * @param string[] $args + * @param string $help + */ function addCallback($method, $callback, $args, $help) { $this->callbacks[$method] = $callback; $this->signatures[$method] = $args; diff --git a/inc/Input.class.php b/inc/Input.class.php index 94da2a10e..f4a4612df 100644 --- a/inc/Input.class.php +++ b/inc/Input.class.php @@ -83,7 +83,6 @@ class Input { * * @see isset * @param string $name Parameter name - * @return bool */ public function remove($name) { if(isset($this->access[$name])) { @@ -146,7 +145,7 @@ class Input { * Access a request parameter as int * * @param string $name Parameter name - * @param mixed $default Default to return if parameter isn't set or is an array + * @param int $default Default to return if parameter isn't set or is an array * @param bool $nonempty Return $default if parameter is set but empty() * @return int */ @@ -164,7 +163,7 @@ class Input { * Access a request parameter as string * * @param string $name Parameter name - * @param mixed $default Default to return if parameter isn't set or is an array + * @param string $default Default to return if parameter isn't set or is an array * @param bool $nonempty Return $default if parameter is set but empty() * @return string */ @@ -246,7 +245,7 @@ class Input { * * This function returns the $INPUT object itself for easy chaining * - * @param $name + * @param string $name * @return Input */ public function extract($name){ diff --git a/inc/JpegMeta.php b/inc/JpegMeta.php index 3b6c6694c..d50bad9b7 100644 --- a/inc/JpegMeta.php +++ b/inc/JpegMeta.php @@ -133,6 +133,9 @@ class JpegMeta { * through one function * * @author Andreas Gohr + * + * @param array|string $fields field name or array with field names + * @return bool|string */ function getField($fields) { if(!is_array($fields)) $fields = array($fields); @@ -178,6 +181,10 @@ class JpegMeta { * through one function * * @author Andreas Gohr + * + * @param string $field field name + * @param string $value + * @return bool success or fail */ function setField($field, $value) { if(strtolower(substr($field,0,5)) == 'iptc.'){ @@ -194,6 +201,9 @@ class JpegMeta { * through one function * * @author Andreas Gohr + * + * @param string $field field name + * @return bool */ function deleteField($field) { if(strtolower(substr($field,0,5)) == 'iptc.'){ @@ -209,6 +219,9 @@ class JpegMeta { * Return a date field * * @author Andreas Gohr + * + * @param string $field + * @return false|string */ function getDateField($field) { if (!isset($this->_info['dates'])) { @@ -226,6 +239,9 @@ class JpegMeta { * Return a file info field * * @author Andreas Gohr + * + * @param string $field field name + * @return false|string */ function getFileField($field) { if (!isset($this->_info['file'])) { @@ -244,6 +260,8 @@ class JpegMeta { * * @author Andreas Gohr * @todo handle makernotes + * + * @return false|string */ function getCamera(){ $make = $this->getField(array('Exif.Make','Exif.TIFFMake')); @@ -257,6 +275,8 @@ class JpegMeta { * Return shutter speed as a ratio * * @author Joe Lapp + * + * @return string */ function getShutterSpeed() { if (!isset($this->_info['exif'])) { @@ -275,6 +295,9 @@ class JpegMeta { * Return an EXIF field * * @author Sebastian Delmont + * + * @param string $field field name + * @return false|string */ function getExifField($field) { if (!isset($this->_info['exif'])) { @@ -296,6 +319,9 @@ class JpegMeta { * Return an XMP field * * @author Hakan Sandell + * + * @param string $field field name + * @return false|string */ function getXmpField($field) { if (!isset($this->_info['xmp'])) { @@ -317,6 +343,9 @@ class JpegMeta { * Return an Adobe Field * * @author Sebastian Delmont + * + * @param string $field field name + * @return false|string */ function getAdobeField($field) { if (!isset($this->_info['adobe'])) { @@ -338,6 +367,9 @@ class JpegMeta { * Return an IPTC field * * @author Sebastian Delmont + * + * @param string $field field name + * @return false|string */ function getIPTCField($field) { if (!isset($this->_info['iptc'])) { @@ -360,6 +392,10 @@ class JpegMeta { * * @author Sebastian Delmont * @author Joe Lapp + * + * @param string $field field name + * @param string $value + * @return bool */ function setExifField($field, $value) { if (!isset($this->_info['exif'])) { @@ -390,6 +426,10 @@ class JpegMeta { * Set an Adobe Field * * @author Sebastian Delmont + * + * @param string $field field name + * @param string $value + * @return bool */ function setAdobeField($field, $value) { if (!isset($this->_info['adobe'])) { @@ -414,6 +454,10 @@ class JpegMeta { * dimensions * * @author Andreas Gohr + * + * @param int $maxwidth + * @param int $maxheight + * @return float|int */ function getResizeRatio($maxwidth,$maxheight=0){ if(!$maxheight) $maxheight = $maxwidth; @@ -443,6 +487,10 @@ class JpegMeta { * Set an IPTC field * * @author Sebastian Delmont + * + * @param string $field field name + * @param string $value + * @return bool */ function setIPTCField($field, $value) { if (!isset($this->_info['iptc'])) { @@ -466,6 +514,9 @@ class JpegMeta { * Delete an EXIF field * * @author Sebastian Delmont + * + * @param string $field field name + * @return bool */ function deleteExifField($field) { if (!isset($this->_info['exif'])) { @@ -487,6 +538,9 @@ class JpegMeta { * Delete an Adobe field * * @author Sebastian Delmont + * + * @param string $field field name + * @return bool */ function deleteAdobeField($field) { if (!isset($this->_info['adobe'])) { @@ -508,6 +562,9 @@ class JpegMeta { * Delete an IPTC field * * @author Sebastian Delmont + * + * @param string $field field name + * @return bool */ function deleteIPTCField($field) { if (!isset($this->_info['iptc'])) { @@ -529,7 +586,7 @@ class JpegMeta { * Get the image's title, tries various fields * * @param int $max maximum number chars (keeps words) - * @return bool|mixed|string + * @return false|string * * @author Andreas Gohr */ @@ -556,6 +613,8 @@ class JpegMeta { * Gather various date fields * * @author Sebastian Delmont + * + * @return array|bool */ function getDates() { $this->_parseAll(); @@ -692,6 +751,8 @@ class JpegMeta { * Get the image width, tries various fields * * @author Sebastian Delmont + * + * @return false|string */ function getWidth() { if (!isset($this->_info['sof'])) { @@ -721,6 +782,8 @@ class JpegMeta { * Get the image height, tries various fields * * @author Sebastian Delmont + * + * @return false|string */ function getHeight() { if (!isset($this->_info['sof'])) { @@ -750,6 +813,8 @@ class JpegMeta { * Get an dimension string for use in img tag * * @author Sebastian Delmont + * + * @return false|string */ function getDimStr() { if ($this->_markers == null) { @@ -766,6 +831,9 @@ class JpegMeta { * Checks for an embedded thumbnail * * @author Sebastian Delmont + * + * @param string $which possible values: 'any', 'exif' or 'adobe' + * @return false|string */ function hasThumbnail($which = 'any') { if (($which == 'any') || ($which == 'exif')) { @@ -807,6 +875,9 @@ class JpegMeta { * Send embedded thumbnail to browser * * @author Sebastian Delmont + * + * @param string $which possible values: 'any', 'exif' or 'adobe' + * @return bool */ function sendThumbnail($which = 'any') { $data = null; @@ -857,6 +928,9 @@ class JpegMeta { * * @author Sebastian Delmont * @author Andreas Gohr + * + * @param string $fileName file name or empty string for a random name + * @return bool */ function save($fileName = "") { if ($fileName == "") { diff --git a/inc/Mailer.class.php b/inc/Mailer.class.php index fb9ed460c..087d82c99 100644 --- a/inc/Mailer.class.php +++ b/inc/Mailer.class.php @@ -108,6 +108,9 @@ class Mailer { /** * Callback function to automatically embed images referenced in HTML templates + * + * @param array $matches + * @return string placeholder */ protected function autoembed_cb($matches) { static $embeds = 0; @@ -160,6 +163,8 @@ class Mailer { * * Whatever is set here is directly passed to PHP's mail() command as last * parameter. Depending on the PHP setup this might break mailing alltogether + * + * @param string $param */ public function setParameters($param) { $this->sendparam = $param; @@ -265,6 +270,8 @@ class Mailer { * Placeholders can be used to reference embedded attachments * * You probably want to use setBody() instead + * + * @param string $html */ public function setHTML($html) { $this->html = $html; @@ -274,6 +281,8 @@ class Mailer { * Set the plain text part of the mail * * You probably want to use setBody() instead + * + * @param string $text */ public function setText($text) { $this->text = $text; @@ -340,8 +349,8 @@ class Mailer { * Example: * cc("föö , me@somewhere.com","TBcc"); * - * @param string|array $addresses Multiple adresses separated by commas or as array - * @return bool|string the prepared header (can contain multiple lines) + * @param string|string[] $addresses Multiple adresses separated by commas or as array + * @return false|string the prepared header (can contain multiple lines) */ public function cleanAddress($addresses) { // No named recipients for To: in Windows (see FS#652) @@ -418,6 +427,8 @@ class Mailer { * Prepare the mime multiparts for all attachments * * Replaces placeholders in the HTML with the correct CIDs + * + * @return string mime multiparts */ protected function prepareAttachments() { $mime = ''; @@ -565,9 +576,9 @@ class Mailer { /** * Returns a complete, EOL terminated header line, wraps it if necessary * - * @param $key - * @param $val - * @return string + * @param string $key + * @param string $val + * @return string line */ protected function wrappedHeaderLine($key, $val){ return wordwrap("$key: $val", 78, MAILHEADER_EOL.' ').MAILHEADER_EOL; diff --git a/inc/PassHash.class.php b/inc/PassHash.class.php index db6a3a77c..15f896dcf 100644 --- a/inc/PassHash.class.php +++ b/inc/PassHash.class.php @@ -16,8 +16,9 @@ class PassHash { * match true is is returned else false * * @author Andreas Gohr - * @param $clear string Clear-Text password - * @param $hash string Hash to compare against + * + * @param string $clear Clear-Text password + * @param string $hash Hash to compare against * @return bool */ function verify_hash($clear, $hash) { @@ -109,9 +110,9 @@ class PassHash { * If $salt is not null, the value is kept, but the lenght restriction is * applied (unless, $cut is false). * - * @param string &$salt The salt, pass null if you want one generated - * @param int $len The length of the salt - * @param bool $cut Apply length restriction to existing salt? + * @param string|null &$salt The salt, pass null if you want one generated + * @param int $len The length of the salt + * @param bool $cut Apply length restriction to existing salt? */ public function init_salt(&$salt, $len = 32, $cut = true) { if(is_null($salt)) { @@ -135,6 +136,7 @@ class PassHash { * @author Andreas Gohr * @author * @link http://de.php.net/manual/en/function.crypt.php#73619 + * * @param string $clear The clear text to hash * @param string $salt The salt to use, null for random * @return string Hashed password @@ -175,6 +177,7 @@ class PassHash { * * @author * @link http://de.php.net/manual/en/function.crypt.php#73619 + * * @param string $clear The clear text to hash * @param string $salt The salt to use, null for random * @param string $magic The hash identifier (apr1 or 1) @@ -337,6 +340,7 @@ class PassHash { * an exception. * * @link http://www.openwall.com/phpass/ + * * @param string $clear The clear text to hash * @param string $salt The salt to use, null for random * @param string $magic The hash identifier (P or H) @@ -404,6 +408,7 @@ class PassHash { * This is used by the Django Python framework * * @link http://docs.djangoproject.com/en/dev/topics/auth/#passwords + * * @param string $clear The clear text to hash * @param string $salt The salt to use, null for random * @return string Hashed password @@ -420,6 +425,7 @@ class PassHash { * This is used by the Django Python framework * * @link http://docs.djangoproject.com/en/dev/topics/auth/#passwords + * * @param string $clear The clear text to hash * @param string $salt The salt to use, null for random * @return string Hashed password @@ -486,6 +492,7 @@ class PassHash { * method 'A' is not supported. * * @link http://www.mediawiki.org/wiki/Manual_talk:User_table#user_password_column + * * @param string $clear The clear text to hash * @param string $salt The salt to use, null for random * @return string Hashed password @@ -511,7 +518,6 @@ class PassHash { * @param string $data Message to be hashed. * @param string $key Shared secret key used for generating the HMAC variant of the message digest. * @param bool $raw_output When set to TRUE, outputs raw binary data. FALSE outputs lowercase hexits. - * * @return string */ public static function hmac($algo, $data, $key, $raw_output = false) { @@ -545,9 +551,8 @@ class PassHash { /** * Use DokuWiki's secure random generator if available * - * @param $min - * @param $max - * + * @param int $min + * @param int $max * @return int */ protected function random($min, $max){ diff --git a/inc/RemoteAPICore.php b/inc/RemoteAPICore.php index 8c7a0e846..b34fe7f20 100644 --- a/inc/RemoteAPICore.php +++ b/inc/RemoteAPICore.php @@ -13,6 +13,11 @@ class RemoteAPICore { $this->api = $api; } + /** + * Returns details about the core methods + * + * @return array + */ function __getRemoteInfo() { return array( 'dokuwiki.getVersion' => array( @@ -158,19 +163,27 @@ class RemoteAPICore { ); } + /** + * @return string + */ function getVersion() { return getVersion(); } + /** + * @return int unix timestamp + */ function getTime() { return time(); } /** * Return a raw wiki page + * * @param string $id wiki page id - * @param string $rev revision number of the page - * @return page text. + * @param int|string $rev revision timestamp of the page or empty string + * @return string page text. + * @throws RemoteAccessDeniedException if no permission for page */ function rawPage($id,$rev=''){ $id = $this->resolvePageId($id); @@ -189,8 +202,11 @@ class RemoteAPICore { * Return a media file * * @author Gina Haeussge + * * @param string $id file id - * @return media file + * @return mixed media file + * @throws RemoteAccessDeniedException no permission for media + * @throws RemoteException not exist */ function getAttachment($id){ $id = cleanID($id); @@ -211,6 +227,9 @@ class RemoteAPICore { * Return info about a media file * * @author Gina Haeussge + * + * @param string $id page id + * @return array */ function getAttachmentInfo($id){ $id = cleanID($id); @@ -230,6 +249,11 @@ class RemoteAPICore { /** * Return a wiki page rendered to html + * + * @param string $id page id + * @param string|int $rev revision timestamp or empty string + * @return null|string html + * @throws RemoteAccessDeniedException no access to page */ function htmlPage($id,$rev=''){ $id = $this->resolvePageId($id); @@ -241,6 +265,8 @@ class RemoteAPICore { /** * List all pages - we use the indexer list here + * + * @return array */ function listPages(){ $list = array(); @@ -265,6 +291,12 @@ class RemoteAPICore { /** * List all pages in the given namespace (and below) + * + * @param string $ns + * @param array $opts + * $opts['depth'] recursion level, 0 for all + * $opts['hash'] do md5 sum of content? + * @return array */ function readNamespace($ns,$opts){ global $conf; @@ -281,6 +313,9 @@ class RemoteAPICore { /** * List all pages in the given namespace (and below) + * + * @param string $query + * @return array */ function search($query){ $regex = ''; @@ -314,6 +349,8 @@ class RemoteAPICore { /** * Returns the wiki title. + * + * @return string */ function getTitle(){ global $conf; @@ -328,6 +365,15 @@ class RemoteAPICore { * a regular expression matching their name. * * @author Gina Haeussge + * + * @param string $ns + * @param array $options + * $options['depth'] recursion level, 0 for all + * $options['showmsg'] shows message if invalid media id is used + * $options['pattern'] check given pattern + * $options['hash'] add hashes to result list + * @return array + * @throws RemoteAccessDeniedException no access to the media files */ function listAttachments($ns, $options = array()) { global $conf; @@ -359,6 +405,9 @@ class RemoteAPICore { /** * Return a list of backlinks + * + * @param string $id page id + * @return array */ function listBackLinks($id){ return ft_backlinks($this->resolvePageId($id)); @@ -366,6 +415,12 @@ class RemoteAPICore { /** * Return some basic data about a page + * + * @param string $id page id + * @param string|int $rev revision timestamp or empty string + * @return array + * @throws RemoteAccessDeniedException no access for page + * @throws RemoteException page not exist */ function pageInfo($id,$rev=''){ $id = $this->resolvePageId($id); @@ -395,6 +450,13 @@ class RemoteAPICore { * Save a wiki page * * @author Michael Klier + * + * @param string $id page id + * @param string $text wiki text + * @param array $params parameters: summary, minor edit + * @return bool + * @throws RemoteAccessDeniedException no write access for page + * @throws RemoteException no id, empty new page or locked */ function putPage($id, $text, $params) { global $TEXT; @@ -451,6 +513,11 @@ class RemoteAPICore { /** * Appends text to a wiki page. + * + * @param string $id page id + * @param string $text wiki text + * @param array $params such as summary,minor + * @return bool|string */ function appendPage($id, $text, $params) { $currentpage = $this->rawPage($id); @@ -464,6 +531,12 @@ class RemoteAPICore { * Uploads a file to the wiki. * * Michael Klier + * + * @param string $id page id + * @param string $file + * @param array $params such as overwrite + * @return false|string + * @throws RemoteException */ function putAttachment($id, $file, $params) { $id = cleanID($id); @@ -493,6 +566,11 @@ class RemoteAPICore { * Deletes a file from the wiki. * * @author Gina Haeussge + * + * @param string $id page id + * @return int + * @throws RemoteAccessDeniedException no permissions + * @throws RemoteException file in use or not deleted */ function deleteAttachment($id){ $id = cleanID($id); @@ -511,6 +589,9 @@ class RemoteAPICore { /** * Returns the permissions of a given wiki page + * + * @param string $id page id + * @return int permission level */ function aclCheck($id) { $id = $this->resolvePageId($id); @@ -521,6 +602,10 @@ class RemoteAPICore { * Lists all links contained in a wiki page * * @author Michael Klier + * + * @param string $id page id + * @return array + * @throws RemoteAccessDeniedException no read access for page */ function listLinks($id) { $id = $this->resolvePageId($id); @@ -571,6 +656,10 @@ class RemoteAPICore { * * @author Michael Hamann * @author Michael Klier + * + * @param int $timestamp unix timestamp + * @return array + * @throws RemoteException no valid timestamp */ function getRecentChanges($timestamp) { if(strlen($timestamp) != 10) { @@ -596,7 +685,7 @@ class RemoteAPICore { return $changes; } else { // in case we still have nothing at this point - return new RemoteException('There are no changes in the specified timeframe', 321); + throw new RemoteException('There are no changes in the specified timeframe', 321); } } @@ -605,6 +694,10 @@ class RemoteAPICore { * * @author Michael Hamann * @author Michael Klier + * + * @param int $timestamp unix timestamp + * @return array + * @throws RemoteException no valid timestamp */ function getRecentMediaChanges($timestamp) { if(strlen($timestamp) != 10) @@ -637,6 +730,12 @@ class RemoteAPICore { * Returns a list of available revisions of a given wiki page * * @author Michael Klier + * + * @param string $id page id + * @param int $first skip the first n changelog lines + * @return array + * @throws RemoteAccessDeniedException no read access for page + * @throws RemoteException empty id */ function pageVersions($id, $first) { $id = $this->resolvePageId($id); @@ -714,6 +813,9 @@ class RemoteAPICore { * * Returns an associative array with the keys locked, lockfail, unlocked and * unlockfail, each containing lists of pages. + * + * @param array[] $set list pages with array('lock' => array, 'unlock' => array) + * @return array */ function setLocks($set){ $locked = array(); @@ -748,13 +850,27 @@ class RemoteAPICore { ); } + /** + * Return API version + * + * @return int + */ function getAPIVersion(){ return DOKU_API_VERSION; } + /** + * Login + * + * @param string $user + * @param string $pass + * @return int + */ function login($user,$pass){ global $conf; + /** @var DokuWiki_Auth_Plugin $auth */ global $auth; + if(!$conf['useacl']) return 0; if(!$auth) return 0; @@ -775,6 +891,11 @@ class RemoteAPICore { return $ok; } + /** + * Log off + * + * @return int + */ function logoff(){ global $conf; global $auth; @@ -786,6 +907,12 @@ class RemoteAPICore { return 1; } + /** + * Resolve page id + * + * @param string $id page id + * @return string + */ private function resolvePageId($id) { $id = cleanID($id); if(empty($id)) { diff --git a/inc/Sitemapper.php b/inc/Sitemapper.php index 33f6d7a36..0325f6d44 100644 --- a/inc/Sitemapper.php +++ b/inc/Sitemapper.php @@ -24,6 +24,8 @@ class Sitemapper { * @author Andreas Gohr * @link https://www.google.com/webmasters/sitemaps/docs/en/about.html * @link http://www.sitemaps.org/ + * + * @return bool */ public static function generate(){ global $conf; @@ -75,6 +77,7 @@ class Sitemapper { * * @param $items array The SitemapItems that shall be included in the sitemap. * @return string The sitemap XML. + * * @author Michael Hamann */ private static function getXML($items) { @@ -95,6 +98,7 @@ class Sitemapper { * Helper function for getting the path to the sitemap file. * * @return string The path to the sitemap file. + * * @author Michael Hamann */ public static function getFilePath() { @@ -123,6 +127,8 @@ class Sitemapper { * urls to ping using the SITEMAP_PING event. * * @author Michael Hamann + * + * @return bool */ public static function pingSearchEngines() { //ping search engines... @@ -168,9 +174,9 @@ class SitemapItem { /** * Create a new item. * - * @param $url string The url of the item - * @param $lastmod int Timestamp of the last modification - * @param $changefreq string How frequently the item is likely to change. Valid values: always, hourly, daily, weekly, monthly, yearly, never. + * @param string $url The url of the item + * @param int $lastmod Timestamp of the last modification + * @param string $changefreq How frequently the item is likely to change. Valid values: always, hourly, daily, weekly, monthly, yearly, never. * @param $priority float|string The priority of the item relative to other URLs on your site. Valid values range from 0.0 to 1.0. */ public function __construct($url, $lastmod, $changefreq = null, $priority = null) { @@ -183,9 +189,9 @@ class SitemapItem { /** * Helper function for creating an item for a wikipage id. * - * @param $id string A wikipage id. - * @param $changefreq string How frequently the item is likely to change. Valid values: always, hourly, daily, weekly, monthly, yearly, never. - * @param $priority float|string The priority of the item relative to other URLs on your site. Valid values range from 0.0 to 1.0. + * @param string $id A wikipage id. + * @param string $changefreq How frequently the item is likely to change. Valid values: always, hourly, daily, weekly, monthly, yearly, never. + * @param float|string $priority The priority of the item relative to other URLs on your site. Valid values range from 0.0 to 1.0. * @return SitemapItem The sitemap item. */ public static function createFromID($id, $changefreq = null, $priority = null) { diff --git a/inc/Tar.class.php b/inc/Tar.class.php index 8c7d33fc1..05831df58 100644 --- a/inc/Tar.class.php +++ b/inc/Tar.class.php @@ -105,6 +105,9 @@ class Tar { * * The archive is closed afer reading the contents, because rewinding is not possible in bzip2 streams. * Reopen the file with open() again if you want to do additional operations + * + * @return array + * @throws TarIOException */ public function contents() { if($this->closed || !$this->file) throw new TarIOException('Can not read from a closed archive'); @@ -270,6 +273,7 @@ class Tar { * Add a file to the current TAR archive using an existing file in the filesystem * * @todo handle directory adding + * * @param string $file the original file * @param string $name the name to use for the file in the archive * @throws TarIOException @@ -377,6 +381,10 @@ class Tar { * Returns the created in-memory archive data * * This implicitly calls close() on the Archive + * + * @param int $comptype + * @param int $complevel + * @return mixed|string */ public function getArchive($comptype = Tar::COMPRESS_AUTO, $complevel = 9) { $this->close(); @@ -395,7 +403,7 @@ class Tar { * Note: It more memory effective to specify the filename in the create() function and * let the library work on the new file directly. * - * @param $file + * @param string $file * @param int $comptype * @param int $complevel * @throws TarIOException @@ -571,7 +579,7 @@ class Tar { /** * Cleans up a path and removes relative parts, also strips leading slashes * - * @param string $p_dir + * @param string $path * @return string */ public function cleanPath($path) { @@ -591,7 +599,7 @@ class Tar { /** * Checks if the given compression type is available and throws an exception if not * - * @param $comptype + * @param int $comptype * @throws TarIllegalCompressionException */ protected function compressioncheck($comptype) { diff --git a/inc/actions.php b/inc/actions.php index 5cf63a6ca..68b71a36a 100644 --- a/inc/actions.php +++ b/inc/actions.php @@ -221,6 +221,9 @@ function act_sendheaders($headers) { * Sanitize the action command * * @author Andreas Gohr + * + * @param array|string $act + * @return string */ function act_clean($act){ // check if the action was given as array key @@ -245,6 +248,9 @@ function act_clean($act){ * Add all allowed commands here. * * @author Andreas Gohr + * + * @param array|string $act + * @return string */ function act_validate($act) { global $conf; @@ -284,10 +290,12 @@ function act_validate($act) { * Run permissionchecks * * @author Andreas Gohr + * + * @param string $act action command + * @return string action command */ function act_permcheck($act){ global $INFO; - global $conf; if(in_array($act,array('save','preview','edit','recover'))){ if($INFO['exists']){ @@ -330,6 +338,9 @@ function act_permcheck($act){ * Handle 'draftdel' * * Deletes the draft for the current page and user + * + * @param string $act action command + * @return string action command */ function act_draftdel($act){ global $INFO; @@ -342,6 +353,9 @@ function act_draftdel($act){ * Saves a draft on preview * * @todo this currently duplicates code from ajax.php :-/ + * + * @param string $act action command + * @return string action command */ function act_draftsave($act){ global $INFO; @@ -372,6 +386,9 @@ function act_draftsave($act){ * returns a new action. * * @author Andreas Gohr + * + * @param string $act action command + * @return string action command */ function act_save($act){ global $ID; @@ -410,6 +427,9 @@ function act_save($act){ * Revert to a certain revision * * @author Andreas Gohr + * + * @param string $act action command + * @return string action command */ function act_revert($act){ global $ID; @@ -457,6 +477,9 @@ function act_revert($act){ * Do a redirect after receiving post data * * Tries to add the section id as hash mark after section editing + * + * @param string $id page id + * @param string $preact action command before redirect */ function act_redirect($id,$preact){ global $PRE; @@ -478,7 +501,7 @@ function act_redirect($id,$preact){ /** * Execute the redirect * - * @param array $opts id and fragment for the redirect + * @param array $opts id and fragment for the redirect and the preact */ function act_redirect_execute($opts){ $go = wl($opts['id'],'',true); @@ -492,6 +515,9 @@ function act_redirect_execute($opts){ * Handle 'login', 'logout' * * @author Andreas Gohr + * + * @param string $act action command + * @return string action command */ function act_auth($act){ global $ID; @@ -527,6 +553,9 @@ function act_auth($act){ * Handle 'edit', 'preview', 'recover' * * @author Andreas Gohr + * + * @param string $act action command + * @return string action command */ function act_edit($act){ global $ID; @@ -591,6 +620,9 @@ function act_edit($act){ * * @author Andreas Gohr * @author Michael Klier + * + * @param string $act action command + * @return string action command */ function act_export($act){ global $ID; @@ -671,6 +703,8 @@ function act_export($act){ * Handle sitemap delivery * * @author Michael Hamann + * + * @param string $act action command */ function act_sitemap($act) { global $conf; @@ -719,6 +753,10 @@ function act_sitemap($act) { * Throws exception on error. * * @author Adrian Lang + * + * @param string $act action command + * @return string action command + * @throws Exception if (un)subscribing fails */ function act_subscription($act){ global $lang; @@ -778,6 +816,9 @@ function act_subscription($act){ * default action for the event ACTION_HANDLE_SUBSCRIBE. * * @author Adrian Lang + * + * @param array &$params the parameters: target, style and action + * @throws Exception */ function subscription_handle_post(&$params) { global $INFO; diff --git a/inc/auth.php b/inc/auth.php index dc2b6cad8..3a6a2f65a 100644 --- a/inc/auth.php +++ b/inc/auth.php @@ -127,6 +127,7 @@ function auth_setup() { * Loads the ACL setup and handle user wildcards * * @author Andreas Gohr + * * @return array */ function auth_loadACL() { @@ -173,7 +174,7 @@ function auth_loadACL() { /** * Event hook callback for AUTH_LOGIN_CHECK * - * @param $evdata + * @param array $evdata * @return bool */ function auth_login_wrapper($evdata) { @@ -280,6 +281,7 @@ function auth_login($user, $pass, $sticky = false, $silent = false) { * token is correct. Will exit with a 401 Status if not. * * @author Andreas Gohr + * * @param string $token The authentication token * @return boolean true (or will exit on failure) */ @@ -307,6 +309,7 @@ function auth_validateToken($token) { * NOTE: this is completely unrelated to the getSecurityToken() function * * @author Andreas Gohr + * * @return string The auth token */ function auth_createToken() { @@ -351,6 +354,7 @@ function auth_browseruid() { * and stored in this file. * * @author Andreas Gohr + * * @param bool $addsession if true, the sessionid is added to the salt * @param bool $secure if security is more important than keeping the old value * @return string @@ -378,6 +382,7 @@ function auth_cookiesalt($addsession = false, $secure = false) { * @author Mark Seecof * @author Michael Hamann * @link http://www.php.net/manual/de/function.mt-rand.php#83655 + * * @param int $length number of bytes to get * @return string binary random strings */ @@ -444,6 +449,7 @@ function auth_randombytes($length) { * * @author Michael Samuel * @author Michael Hamann + * * @param int $min * @param int $max * @return int @@ -515,6 +521,7 @@ function auth_decrypt($ciphertext, $secret) { * off. It also clears session data. * * @author Andreas Gohr + * * @param bool $keepbc - when true, the breadcrumb data is not cleared */ function auth_logoff($keepbc = false) { @@ -555,6 +562,7 @@ function auth_logoff($keepbc = false) { * * @author Andreas Gohr * @see auth_isadmin + * * @param string $user Username * @param array $groups List of groups the user is in * @param bool $adminonly when true checks if user is admin @@ -599,6 +607,7 @@ function auth_ismanager($user = null, $groups = null, $adminonly = false) { * * @author Andreas Gohr * @see auth_ismanager() + * * @param string $user Username * @param array $groups List of groups the user is in * @return bool @@ -613,9 +622,9 @@ function auth_isadmin($user = null, $groups = null) { * * Note: all input should NOT be nameencoded. * - * @param $memberlist string commaseparated list of allowed users and groups - * @param $user string user to match against - * @param $groups array groups the user is member of + * @param string $memberlist commaseparated list of allowed users and groups + * @param string $user user to match against + * @param array $groups groups the user is member of * @return bool true for membership acknowledged */ function auth_isMember($memberlist, $user, array $groups) { @@ -678,6 +687,7 @@ function auth_quickaclcheck($id) { * Returns the maximum rights a user has for the given ID or its namespace * * @author Andreas Gohr + * * @triggers AUTH_ACL_CHECK * @param string $id page ID (needs to be resolved and cleaned) * @param string $user Username @@ -700,6 +710,7 @@ function auth_aclcheck($id, $user, $groups) { * DO NOT CALL DIRECTLY, use auth_aclcheck() instead * * @author Andreas Gohr + * * @param array $data event data * @return int permission level */ @@ -832,6 +843,10 @@ function auth_aclcheck_cb($data) { * * @author Andreas Gohr * @see rawurldecode() + * + * @param string $name + * @param bool $skip_group + * @return string */ function auth_nameencode($name, $skip_group = false) { global $cache_authname; @@ -913,6 +928,7 @@ function auth_pwgen($foruser = '') { * Sends a password to the given user * * @author Andreas Gohr + * * @param string $user Login name of the user * @param string $password The new password in clear text * @return bool true on success @@ -948,6 +964,7 @@ function auth_sendPassword($user, $password) { * This registers a new user - Data is read directly from $_POST * * @author Andreas Gohr + * * @return bool true on success, false on any error */ function register() { @@ -1280,6 +1297,7 @@ function act_resendpwd() { * is chosen. * * @author Andreas Gohr + * * @param string $clear The clear text password * @param string $method The hashing method * @param string $salt A salt, null for random @@ -1304,6 +1322,7 @@ function auth_cryptPassword($clear, $method = '', $salt = null) { * Verifies a cleartext password against a crypted hash * * @author Andreas Gohr + * * @param string $clear The clear text password * @param string $crypt The hash to compare with * @return bool true if both match diff --git a/inc/blowfish.php b/inc/blowfish.php index bcf5804a2..7499515bc 100644 --- a/inc/blowfish.php +++ b/inc/blowfish.php @@ -356,7 +356,7 @@ class Horde_Cipher_blowfish * Encrypt a block on data. * * @param String $block The data to encrypt - * @param optional String $key The key to use + * @param String $key optional The key to use * * @return String the encrypted output */ @@ -404,8 +404,8 @@ class Horde_Cipher_blowfish /** * Decrypt a block on data. * - * @param String $block The data to decrypt - * @param optional String $key The key to use + * @param String $block The data to decrypt + * @param String $key optional The key to use * * @return String the decrypted output */ @@ -452,6 +452,7 @@ class Horde_Cipher_blowfish /** * Converts a text key into an array. * + * @param string $key * @return array The key. */ function _formatKey($key) { @@ -464,8 +465,8 @@ class Horde_Cipher_blowfish /** * Encryption using blowfish algorithm * - * @param string original data - * @param string the secret + * @param string $data original data + * @param string $secret the secret * * @return string the encrypted result * @@ -493,8 +494,8 @@ function PMA_blowfish_encrypt($data, $secret) { /** * Decryption using blowfish algorithm * - * @param string encrypted data - * @param string the secret + * @param string $encdata encrypted data + * @param string $secret the secret * * @return string original data * diff --git a/inc/changelog.php b/inc/changelog.php index 8c14f21b0..e2826e4b3 100644 --- a/inc/changelog.php +++ b/inc/changelog.php @@ -725,8 +725,10 @@ abstract class ChangeLog { * If file larger than $chuncksize, only chunck is read that could contain $rev. * * @param int $rev revision timestamp - * @return array(fp, array(changeloglines), $head, $tail, $eof)|bool - * returns false when not succeed. fp only defined for chuck reading, needs closing. + * @return array|false + * if success returns array(fp, array(changeloglines), $head, $tail, $eof) + * where fp only defined for chuck reading, needs closing. + * otherwise false */ protected function readloglines($rev) { $file = $this->getChangelogFilename(); diff --git a/inc/cli.php b/inc/cli.php index 25bfddf7d..29d76ece1 100644 --- a/inc/cli.php +++ b/inc/cli.php @@ -108,7 +108,7 @@ abstract class DokuCLI { /** * Print an error message * - * @param $string + * @param string $string */ public function error($string) { $this->colors->ptln("E: $string", 'red', STDERR); @@ -117,7 +117,7 @@ abstract class DokuCLI { /** * Print a success message * - * @param $string + * @param string $string */ public function success($string) { $this->colors->ptln("S: $string", 'green', STDERR); @@ -126,7 +126,7 @@ abstract class DokuCLI { /** * Print an info message * - * @param $string + * @param string $string */ public function info($string) { $this->colors->ptln("I: $string", 'cyan', STDERR); @@ -199,8 +199,8 @@ class DokuCLI_Colors { /** * Convenience function to print a line in a given color * - * @param $line - * @param $color + * @param string $line + * @param string $color * @param resource $channel */ public function ptln($line, $color, $channel = STDOUT) { @@ -470,8 +470,8 @@ class DokuCLI_Options { * Can only be used after parseOptions() has been run * * @param string $option - * @param mixed $default what to return if the option was not set - * @return mixed + * @param bool|string $default what to return if the option was not set + * @return false|string */ public function getOpt($option, $default = false) { if(isset($this->options[$option])) return $this->options[$option]; @@ -593,8 +593,8 @@ class DokuCLI_Options { /** * Displays text in multiple word wrapped columns * - * @param array $widths list of column widths (in characters) - * @param array $texts list of texts for each column + * @param int[] $widths list of column widths (in characters) + * @param string[] $texts list of texts for each column * @return string */ private function tableFormat($widths, $texts) { @@ -640,6 +640,11 @@ class DokuCLI_Exception extends Exception { const E_OPT_ABIGUOUS = 4; //Option abiguous const E_ARG_READ = 5; //Could not read argv + /** + * @param string $message The Exception message to throw. + * @param int $code The Exception code + * @param Exception $previous The previous exception used for the exception chaining. + */ public function __construct($message = "", $code = 0, Exception $previous = null) { if(!$code) $code = DokuCLI_Exception::E_ANY; parent::__construct($message, $code, $previous); diff --git a/inc/common.php b/inc/common.php index 91a068bb0..444e90198 100644 --- a/inc/common.php +++ b/inc/common.php @@ -49,7 +49,7 @@ function ptln($string, $indent = 0) { * * @author Andreas Gohr * - * @param $string string being stripped + * @param string $string being stripped * @return string */ function stripctl($string) { @@ -62,6 +62,7 @@ function stripctl($string) { * @author Andreas Gohr * @link http://en.wikipedia.org/wiki/Cross-site_request_forgery * @link http://christ1an.blogspot.com/2007/04/preventing-csrf-efficiently.html + * * @return string */ function getSecurityToken() { @@ -95,7 +96,7 @@ function checkSecurityToken($token = null) { * @author Andreas Gohr * * @param bool $print if true print the field, otherwise html of the field is returned - * @return void|string html of hidden form field + * @return string html of hidden form field */ function formSecurityToken($print = true) { $ret = '
'."\n"; @@ -336,7 +337,7 @@ function buildAttributes($params, $skipempty = false) { * * @author Andreas Gohr * - * @return array(pageid=>name, ... ) + * @return string[string] with the data: array(pageid=>name, ... ) */ function breadcrumbs() { // we prepare the breadcrumbs early for quick session closing @@ -1110,7 +1111,7 @@ function parsePageTemplate(&$data) { * @param string $range in form "from-to" * @param string $id page id * @param string $rev optional, the revision timestamp - * @return array with three slices + * @return string[] with three slices */ function rawWikiSlices($range, $id, $rev = '') { $text = io_readWikiPage(wikiFN($id, $rev), $id, $rev); @@ -1296,7 +1297,7 @@ function saveOldRevision($id) { * @param int|string $rev Old page revision * @param string $summary What changed * @param boolean $minor Is this a minor edit? - * @param array $replace Additional string substitutions, @KEY@ to be replaced by value + * @param string[] $replace Additional string substitutions, @KEY@ to be replaced by value * @return bool * * @author Andreas Gohr @@ -1376,8 +1377,8 @@ 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 @@ -1914,7 +1915,7 @@ function set_doku_pref($pref, $val) { /** * Strips source mapping declarations from given text #601 * - * @param &string $text reference to the CSS or JavaScript code to clean + * @param string &$text reference to the CSS or JavaScript code to clean */ function stripsourcemaps(&$text){ $text = preg_replace('/^(\/\/|\/\*)[@#]\s+sourceMappingURL=.*?(\*\/)?$/im', '\\1\\2', $text); diff --git a/inc/confutils.php b/inc/confutils.php index 31371d41f..85bf5128c 100644 --- a/inc/confutils.php +++ b/inc/confutils.php @@ -14,6 +14,10 @@ * are returned. * * @author Andreas Gohr + * + * @param string $file file name + * @param bool $knownonly + * @return array with extension, mimetype and if it should be downloaded */ function mimetype($file, $knownonly=true){ $mtypes = getMimeTypes(); // known mimetypes diff --git a/inc/events.php b/inc/events.php index 318a7617e..4cd06b9f9 100644 --- a/inc/events.php +++ b/inc/events.php @@ -165,13 +165,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 $advise string - * @param $obj object object in whose scope method is to be executed, + * @param string $event string name used by the event, (incl '_before' or '_after' for triggers) + * @param string $advise + * @param object $obj object in whose scope method is to be executed, * if NULL, method is assumed to be a globally available function - * @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) + * @param string $method event handler function + * @param mixed $param data passed to the event handler + * @param int $seq sequence number for ordering hook execution (ascending) */ function register_hook($event, $advise, $obj, $method, $param=null, $seq=0) { $seq = (int)$seq; @@ -216,14 +216,14 @@ 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 string $name name for the event + * @param mixed $data event data + * @param callback $action (optional, default=NULL) default action, a php callback function + * @param bool $canPreventDefault (optional, default=true) can hooks prevent the default action * * @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 + * by default this is the return value of the default action however + * it can be set or modified by event handler hooks */ function trigger_event($name, &$data, $action=null, $canPreventDefault=true) { diff --git a/inc/fetch.functions.php b/inc/fetch.functions.php index c61c54503..70becc01e 100644 --- a/inc/fetch.functions.php +++ b/inc/fetch.functions.php @@ -16,6 +16,7 @@ * @author Andreas Gohr * @author Ben Coburn * @author Gerry Weissbach + * * @param string $file local file to send * @param string $mime mime type of the file * @param bool $dl set to true to force a browser download @@ -96,12 +97,13 @@ function sendFile($file, $mime, $dl, $cache, $public = false, $orig = null) { * WRITE: MEDIA, FILE, array( STATUS, STATUSMESSAGE ) * * @author Gerry Weissbach + * * @param string $media reference to the media id * @param string $file reference to the file variable * @param string $rev * @param int $width * @param int $height - * @return array(STATUS, STATUSMESSAGE) + * @return array as array(STATUS, STATUSMESSAGE) */ function checkFileStatus(&$media, &$file, $rev = '', $width=0, $height=0) { global $MIME, $EXT, $CACHE, $INPUT; @@ -149,6 +151,9 @@ function checkFileStatus(&$media, &$file, $rev = '', $width=0, $height=0) { * Resolves named constants * * @author Andreas Gohr + * + * @param string $cache + * @return int cachetime in seconds */ function calc_cache($cache) { global $conf; diff --git a/inc/form.php b/inc/form.php index fadc71d3e..00eea9b3a 100644 --- a/inc/form.php +++ b/inc/form.php @@ -52,6 +52,7 @@ class Doku_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 */ function Doku_Form($params, $action=false, $method=false, $enctype=false) { @@ -84,6 +85,7 @@ class Doku_Form { * Usually results in a border drawn around the form. * * @param string $legend Label that will be printed with the border. + * * @author Tom N Harris */ function startFieldset($legend) { @@ -115,6 +117,7 @@ class Doku_Form { * * @param string $name Field name. * @param string $value Field value. If null, remove a previously added field. + * * @author Tom N Harris */ function addHidden($name, $value) { @@ -132,6 +135,7 @@ class Doku_Form { * If string, it is printed without escaping special chars. * * * @param string|array $elem Pseudo-tag or string to add to the form. + * * @author Tom N Harris */ function addElement($elem) { @@ -145,6 +149,7 @@ class Doku_Form { * * @param string $pos 0-based index where the element will be inserted. * @param string|array $elem Pseudo-tag or string to add to the form. + * * @author Tom N Harris */ function insertElement($pos, $elem) { @@ -158,6 +163,7 @@ class Doku_Form { * * @param int $pos 0-based index the element will be placed at. * @param string|array $elem Pseudo-tag or string to add to the form. + * * @author Tom N Harris */ function replaceElement($pos, $elem) { @@ -172,7 +178,8 @@ class Doku_Form { * Gets the position of the first of a type of element. * * @param string $type Element type to look for. - * @return int position of element if found, otherwise false + * @return int|false position of element if found, otherwise false + * * @author Tom N Harris */ function findElementByType($type) { @@ -189,7 +196,8 @@ class Doku_Form { * Gets the position of the element with an ID attribute. * * @param string $id ID of the element to find. - * @return int position of element if found, otherwise false + * @return int|false position of element if found, otherwise false + * * @author Tom N Harris */ function findElementById($id) { @@ -207,7 +215,8 @@ class Doku_Form { * * @param string $name Attribute name. * @param string $value Attribute value. - * @return int position of element if found, otherwise false + * @return int|false position of element if found, otherwise false + * * @author Tom N Harris */ function findElementByAttribute($name, $value) { @@ -227,6 +236,7 @@ class Doku_Form { * * @param int $pos 0-based index * @return array reference pseudo-element + * * @author Tom N Harris */ function &getElementAt($pos) { @@ -243,6 +253,8 @@ class Doku_Form { * 'form_$type'. The function should return the HTML to be printed. * * @author Tom N Harris + * + * @return string html of the form */ function getForm() { global $lang; @@ -310,6 +322,7 @@ class Doku_Form { * @param string $tag Tag name. * @param array $attrs Optional attributes. * @return array pseudo-tag + * * @author Tom N Harris */ function form_makeTag($tag, $attrs=array()) { @@ -326,6 +339,7 @@ function form_makeTag($tag, $attrs=array()) { * @param string $tag Tag name. * @param array $attrs Optional attributes. * @return array pseudo-tag + * * @author Tom N Harris */ function form_makeOpenTag($tag, $attrs=array()) { @@ -341,6 +355,7 @@ function form_makeOpenTag($tag, $attrs=array()) { * * @param string $tag Tag name. * @return array pseudo-tag + * * @author Tom N Harris */ function form_makeCloseTag($tag) { @@ -358,6 +373,7 @@ function form_makeCloseTag($tag) { * @param string $text Text to fill the field with. * @param array $attrs Optional attributes. * @return array pseudo-tag + * * @author Tom N Harris */ function form_makeWikiText($text, $attrs=array()) { @@ -378,6 +394,7 @@ function form_makeWikiText($text, $attrs=array()) { * @param string $value (optional) Displayed label. Uses $act if not provided. * @param array $attrs Optional attributes. * @return array pseudo-tag + * * @author Tom N Harris */ function form_makeButton($type, $act, $value='', $attrs=array()) { @@ -406,6 +423,7 @@ function form_makeButton($type, $act, $value='', $attrs=array()) { * reference it with a 'for' attribute. * @param array $attrs Optional attributes. * @return array pseudo-tag + * * @author Tom N Harris */ function form_makeField($type, $name, $value='', $label=null, $id='', $class='', $attrs=array()) { @@ -522,6 +540,18 @@ function form_makeRadioField($name, $value='1', $label=null, $id='', $class='', * a string. * * @author Tom N Harris + * + * @param string $name Name attribute of the input. + * @param string[]|array[] $values The list of values can be strings, arrays of (value,text), + * or an associative array with the values as keys and labels as values. + * @param string|int $selected default selected value, string or index number + * @param string $class Class attribute of the label. If this is 'block', + * then a line break will be added after the field. + * @param string $label Label that will be printed before the input. + * @param string $id ID attribute of the input. If set, the label will + * reference it with a 'for' attribute. + * @param array $attrs Optional attributes. + * @return array pseudo-tag */ function form_makeMenuField($name, $values, $selected='', $label=null, $id='', $class='', $attrs=array()) { if (is_null($label)) $label = $name; @@ -556,6 +586,18 @@ function form_makeMenuField($name, $values, $selected='', $label=null, $id='', $ * Items are selected by supplying its value or an array of values. * * @author Tom N Harris + * + * @param string $name Name attribute of the input. + * @param string[]|array[] $values The list of values can be strings, arrays of (value,text), + * or an associative array with the values as keys and labels as values. + * @param array|string $selected value or array of values of the items that need to be selected + * @param string $class Class attribute of the label. If this is 'block', + * then a line break will be added after the field. + * @param string $label Label that will be printed before the input. + * @param string $id ID attribute of the input. If set, the label will + * reference it with a 'for' attribute. + * @param array $attrs Optional attributes. + * @return array pseudo-tag */ function form_makeListboxField($name, $values, $selected='', $label=null, $id='', $class='', $attrs=array()) { if (is_null($label)) $label = $name; @@ -595,6 +637,9 @@ function form_makeListboxField($name, $values, $selected='', $label=null, $id='' * Attributes are passed to buildAttributes() * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html of tag */ function form_tag($attrs) { return '<'.$attrs['_tag'].' '.buildAttributes($attrs,true).'/>'; @@ -608,6 +653,9 @@ function form_tag($attrs) { * Attributes are passed to buildAttributes() * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html of tag */ function form_opentag($attrs) { return '<'.$attrs['_tag'].' '.buildAttributes($attrs,true).'>'; @@ -621,6 +669,9 @@ function form_opentag($attrs) { * There are no attributes. * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html of tag */ function form_closetag($attrs) { return ''; @@ -634,6 +685,9 @@ function form_closetag($attrs) { * Attributes are passed to buildAttributes() * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html */ function form_openfieldset($attrs) { $s = '
'; @@ -648,6 +702,8 @@ function form_openfieldset($attrs) { * There are no attributes. * * @author Tom N Harris + * + * @return string html */ function form_closefieldset() { return '
'; @@ -661,6 +717,9 @@ function form_closefieldset() { * Value is passed to formText() * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html */ function form_hidden($attrs) { return ''; @@ -674,6 +733,9 @@ function form_hidden($attrs) { * Text will be passed to formText(), attributes to buildAttributes() * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html */ function form_wikitext($attrs) { // mandatory attributes @@ -693,6 +755,9 @@ function form_wikitext($attrs) { * Other attributes are passed to buildAttributes() * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html */ function form_button($attrs) { $p = (!empty($attrs['_action'])) ? 'name="do['.$attrs['_action'].']" ' : ''; @@ -708,6 +773,9 @@ function form_button($attrs) { * Other attributes are passed to buildAttributes() for the input tag. * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html */ function form_field($attrs) { $s = ' + * + * @param array $attrs attributes + * @return string html */ function form_fieldright($attrs) { $s = ' + * + * @param array $attrs attributes + * @return string html */ function form_textfield($attrs) { // mandatory attributes @@ -773,6 +847,9 @@ function form_textfield($attrs) { * Other attributes are passed to buildAttributes() for the input tag. * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html */ function form_passwordfield($attrs) { // mandatory attributes @@ -798,6 +875,9 @@ function form_passwordfield($attrs) { * Other attributes are passed to buildAttributes() for the input tag * * @author Michael Klier + * + * @param array $attrs attributes + * @return string html */ function form_filefield($attrs) { $s = ' + * + * @param array $attrs attributes + * @return string html */ function form_checkboxfield($attrs) { // mandatory attributes @@ -853,6 +936,9 @@ function form_checkboxfield($attrs) { * Other attributes are passed to buildAttributes() for the input tag. * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html */ function form_radiofield($attrs) { // mandatory attributes @@ -879,6 +965,9 @@ function form_radiofield($attrs) { * Other attributes are passed to buildAttributes() for the input tag. * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html */ function form_menufield($attrs) { $attrs['size'] = '1'; @@ -924,6 +1013,9 @@ function form_menufield($attrs) { * Other attributes are passed to buildAttributes() for the input tag. * * @author Tom N Harris + * + * @param array $attrs attributes + * @return string html */ function form_listboxfield($attrs) { $s = ' * @author Kazutaka Miyasaka + * + * @param array $data event data + * @return array matching documents */ function _ft_pageSearch(&$data) { $Indexer = idx_get_indexer(); @@ -206,6 +212,11 @@ function ft_mediause($id, $ignore_perms = false){ * @triggers SEARCH_QUERY_PAGELOOKUP * @author Andreas Gohr * @author Adrian Lang + * + * @param string $id page id + * @param bool $in_ns match against namespace as well? + * @param bool $in_title search in title? + * @return string[] */ function ft_pageLookup($id, $in_ns=false, $in_title=false){ $data = compact('id', 'in_ns', 'in_title'); @@ -213,6 +224,12 @@ function ft_pageLookup($id, $in_ns=false, $in_title=false){ return trigger_event('SEARCH_QUERY_PAGELOOKUP', $data, '_ft_pageLookup'); } +/** + * Returns list of pages as array(pageid => First Heading) + * + * @param array &$data event data + * @return string[] + */ function _ft_pageLookup(&$data){ // split out original parameters $id = $data['id']; @@ -270,6 +287,10 @@ function _ft_pageLookup(&$data){ * Tiny helper function for comparing the searched title with the title * from the search index. This function is a wrapper around stripos with * adapted argument order and return value. + * + * @param string $search searched title + * @param string $title title from index + * @return bool */ function _ft_pageLookupTitleCompare($search, $title) { return stripos($title, $search) !== false; @@ -279,6 +300,10 @@ function _ft_pageLookupTitleCompare($search, $title) { * Sort pages based on their namespace level first, then on their string * values. This makes higher hierarchy pages rank higher than lower hierarchy * pages. + * + * @param string $a + * @param string $b + * @return int Returns < 0 if $a is less than $b; > 0 if $a is greater than $b, and 0 if they are equal. */ function ft_pagesorter($a, $b){ $ac = count(explode(':',$a)); @@ -296,6 +321,10 @@ function ft_pagesorter($a, $b){ * * @author Andreas Gohr * @triggers FULLTEXT_SNIPPET_CREATE + * + * @param string $id page id + * @param array $highlight + * @return mixed */ function ft_snippet($id,$highlight){ $text = rawWiki($id); @@ -390,6 +419,9 @@ function ft_snippet($id,$highlight){ /** * Wraps a search term in regex boundary checks. + * + * @param string $term + * @return string */ function ft_snippet_re_preprocess($term) { // do not process asian terms where word boundaries are not explicit @@ -433,6 +465,7 @@ function ft_snippet_re_preprocess($term) { * based upon PEAR's PHP_Compat function for array_intersect_key() * * @param array $args An array of page arrays + * @return array */ function ft_resultCombine($args){ $array_count = count($args); @@ -462,6 +495,8 @@ function ft_resultCombine($args){ * based upon ft_resultCombine() function * * @param array $args An array of page arrays + * @return array + * * @author Kazutaka Miyasaka */ function ft_resultUnite($args) { @@ -485,6 +520,8 @@ function ft_resultUnite($args) { * nearly identical to PHP5's array_diff_key() * * @param array $args An array of page arrays + * @return array + * * @author Kazutaka Miyasaka */ function ft_resultComplement($args) { @@ -507,6 +544,10 @@ function ft_resultComplement($args) { * * @author Andreas Gohr * @author Kazutaka Miyasaka + * + * @param Doku_Indexer $Indexer + * @param string $query search query + * @return array of search formulas */ function ft_queryParser($Indexer, $query){ /** @@ -737,6 +778,12 @@ function ft_queryParser($Indexer, $query){ * This function is used in ft_queryParser() and not for general purpose use. * * @author Kazutaka Miyasaka + * + * @param Doku_Indexer $Indexer + * @param string $term + * @param bool $consider_asian + * @param bool $phrase_mode + * @return string */ function ft_termParser($Indexer, $term, $consider_asian = true, $phrase_mode = false) { $parsed = ''; diff --git a/inc/html.php b/inc/html.php index ce6360175..adcd212ed 100644 --- a/inc/html.php +++ b/inc/html.php @@ -83,6 +83,10 @@ function html_denied() { * inserts section edit buttons if wanted or removes the markers * * @author Andreas Gohr + * + * @param string $text + * @param bool $show show section edit buttons? + * @return string */ function html_secedit($text,$show=true){ global $INFO; @@ -101,8 +105,11 @@ function html_secedit($text,$show=true){ * prepares section edit button data for event triggering * used as a callback in html_secedit * - * @triggers HTML_SECEDIT_BUTTON * @author Andreas Gohr + * + * @param array $matches matches with regexp + * @return string + * @triggers HTML_SECEDIT_BUTTON */ function html_secedit_button($matches){ $data = array('secid' => $matches[1], @@ -121,6 +128,9 @@ function html_secedit_button($matches){ * used as default action form HTML_SECEDIT_BUTTON * * @author Adrian Lang + * + * @param array $data name, section id and target + * @return string html */ function html_secedit_get_button($data) { global $ID; @@ -147,6 +157,8 @@ function html_secedit_get_button($data) { * Just the back to top button (in its own form) * * @author Andreas Gohr + * + * @return string html */ function html_topbtn(){ global $lang; @@ -161,6 +173,15 @@ function html_topbtn(){ * If tooltip exists, the access key tooltip is replaced. * * @author Andreas Gohr + * + * @param string $name + * @param string $id + * @param string $akey access key + * @param string[string] $params key-value pairs added as hidden inputs + * @param string $method + * @param string $tooltip + * @param bool|string $label label text, false: lookup btn_$name in localization + * @return string */ function html_btn($name,$id,$akey,$params,$method='get',$tooltip='',$label=false){ global $conf; @@ -213,9 +234,11 @@ function html_btn($name,$id,$akey,$params,$method='get',$tooltip='',$label=false } /** - * show a wiki page + * Show a wiki page * * @author Andreas Gohr + * + * @param null|string $txt wiki text or null for showing $ID */ function html_show($txt=null){ global $ID; @@ -281,6 +304,10 @@ function html_draft(){ * * @author Andreas Gohr * @author Harry Fuecks + * + * @param string $html + * @param array|string $phrases + * @return string html */ function html_hilight($html,$phrases){ $phrases = (array) $phrases; @@ -299,6 +326,9 @@ function html_hilight($html,$phrases){ * Callback used by html_hilight() * * @author Harry Fuecks + * + * @param array $m matches + * @return string html */ function html_hilight_callback($m) { $hlight = unslash($m[0]); @@ -646,6 +676,9 @@ function html_revisions($first=0, $media_id = false){ * @author Matthias Grimm * @author Ben Coburn * @author Kate Arzamastseva + * + * @param int $first + * @param string $show_changes */ function html_recent($first=0, $show_changes='both'){ global $conf; @@ -833,6 +866,8 @@ function html_recent($first=0, $show_changes='both'){ * Display page index * * @author Andreas Gohr + * + * @param string $ns */ function html_index($ns){ global $conf; @@ -861,6 +896,9 @@ function html_index($ns){ * User function for html_buildlist() * * @author Andreas Gohr + * + * @param array $item + * @return string */ function html_list_index($item){ global $ID, $conf; @@ -891,6 +929,9 @@ function html_list_index($item){ * it gives different classes to opened or closed "folders" * * @author Andreas Gohr + * + * @param array $item + * @return string html */ function html_li_index($item){ if($item['type'] == "f"){ @@ -906,6 +947,9 @@ function html_li_index($item){ * Default List item * * @author Andreas Gohr + * + * @param array $item + * @return string html */ function html_li_default($item){ return '
  • '; @@ -1021,12 +1065,13 @@ function html_backlinks(){ /** * Get header of diff HTML + * * @param string $l_rev Left revisions * @param string $r_rev Right revision * @param string $id Page id, if null $ID is used * @param bool $media If it is for media files * @param bool $inline Return the header on a single line - * @return array HTML snippets for diff header + * @return string[] HTML snippets for diff header */ function html_diff_head($l_rev, $r_rev, $id = null, $media = false, $inline = false) { global $lang; @@ -1482,7 +1527,7 @@ function html_diff_navigationlink($difftype, $linktype, $lrev, $rrev = null) { /** * Insert soft breaks in diff html * - * @param $diffhtml + * @param string $diffhtml * @return string */ function html_insert_softbreaks($diffhtml) { @@ -1521,6 +1566,9 @@ REGEX; * show warning on conflict detection * * @author Andreas Gohr + * + * @param string $text + * @param string $summary */ function html_conflict($text,$summary){ global $ID; @@ -1681,7 +1729,6 @@ function html_edit(){ global $lang; global $conf; global $TEXT; - global $RANGE; if ($INPUT->has('changecheck')) { $check = $INPUT->str('changecheck'); @@ -1783,6 +1830,7 @@ function html_edit(){ * Display the default edit form * * Is the default action for HTML_EDIT_FORMSELECTION. + * * @param mixed[] $param */ function html_edit_form($param) { @@ -1802,6 +1850,8 @@ function html_edit_form($param) { * Adds a checkbox for minor edits for logged in users * * @author Andreas Gohr + * + * @return array|bool */ function html_minoredit(){ global $conf; @@ -2081,6 +2131,9 @@ function html_resendpwd() { * Return the TOC rendered to XHTML * * @author Andreas Gohr + * + * @param array $toc + * @return string html */ function html_TOC($toc){ if(!count($toc)) return ''; @@ -2099,6 +2152,9 @@ function html_TOC($toc){ /** * Callback for html_buildlist + * + * @param array $item + * @return string html */ function html_list_toc($item){ if(isset($item['hid'])){ @@ -2133,6 +2189,7 @@ function html_mktocitem($link, $text, $level, $hash='#'){ * Triggers an event with the form name: HTML_{$name}FORM_OUTPUT * * @author Tom N Harris + * * @param string $name The name of the form * @param Doku_Form $form The form */ @@ -2145,6 +2202,7 @@ function html_form($name, &$form) { /** * Form print function. * Just calls printForm() on the data object. + * * @param Doku_Form $data The form */ function html_form_output($data) { diff --git a/inc/httputils.php b/inc/httputils.php index efeb2a56c..ac79aa176 100644 --- a/inc/httputils.php +++ b/inc/httputils.php @@ -15,6 +15,7 @@ define('HTTP_CHUNK_SIZE',16*1024); * * @author Simon Willison * @link http://simonwillison.net/2003/Apr/23/conditionalGet/ + * * @param int $timestamp lastmodified time of the cache file * @returns void or exits with previously header() commands executed */ @@ -64,6 +65,7 @@ function http_conditionalRequest($timestamp){ * Let the webserver send the given file via x-sendfile method * * @author Chris Smith + * * @param string $file absolute path of file to send * @returns void or exits with previous header() commands executed */ @@ -190,6 +192,9 @@ function http_rangeRequest($fh,$size,$mime){ * (samepath/samefilename.sameext.gz) created after the uncompressed file * * @author Chris Smith + * + * @param string $uncompressed_file + * @return bool */ function http_gzip_valid($uncompressed_file) { $gzip = $uncompressed_file.'.gz'; @@ -206,6 +211,9 @@ function http_gzip_valid($uncompressed_file) { * This function handles output of cacheable resource files. It ses the needed * HTTP headers. If a useable cache is present, it is passed to the web server * and the script is terminated. + * + * @param string $cache cache file name + * @param bool $cache_ok if cache can be used */ function http_cached($cache, $cache_ok) { global $conf; @@ -235,6 +243,9 @@ function http_cached($cache, $cache_ok) { /** * Cache content and print it + * + * @param string $file file name + * @param string $content */ function http_cached_finish($file, $content) { global $conf; diff --git a/inc/indexer.php b/inc/indexer.php index 5ca2f0bb1..ec0c523e0 100644 --- a/inc/indexer.php +++ b/inc/indexer.php @@ -61,6 +61,8 @@ define('IDX_ASIAN', '(?:'.IDX_ASIAN1.'|'.IDX_ASIAN2.'|'.IDX_ASIAN3.')'); * * @author Tom N Harris * @author Michael Hamann + * + * @return int|string */ function idx_get_version(){ static $indexer_version = null; @@ -84,6 +86,9 @@ function idx_get_version(){ * Differs from strlen in handling of asian characters. * * @author Tom N Harris + * + * @param string $w + * @return int */ function wordlen($w){ $l = strlen($w); @@ -115,7 +120,8 @@ class Doku_Indexer { * * @param string $page a page name * @param string $text the body of the page - * @return boolean the function completed successfully + * @return string|boolean the function completed successfully + * * @author Tom N Harris * @author Andreas Gohr */ @@ -190,6 +196,7 @@ class Doku_Indexer { * * @param string $text content of the page * @return array list of word IDs and number of times used + * * @author Andreas Gohr * @author Christopher Smith * @author Tom N Harris @@ -245,7 +252,8 @@ class Doku_Indexer { * @param string $page a page name * @param mixed $key a key string or array of key=>value pairs * @param mixed $value the value or list of values - * @return boolean the function completed successfully + * @return boolean|string the function completed successfully + * * @author Tom N Harris * @author Michael Hamann */ @@ -453,7 +461,8 @@ class Doku_Indexer { * Erases entries in all known indexes. * * @param string $page a page name - * @return boolean the function completed successfully + * @return string|boolean the function completed successfully + * * @author Tom N Harris */ public function deletePage($page) { @@ -474,6 +483,7 @@ class Doku_Indexer { * * @param string $page a page name * @return boolean the function completed successfully + * * @author Tom N Harris */ protected function deletePageNoLock($page) { @@ -568,6 +578,7 @@ class Doku_Indexer { * @param string $text plain text * @param boolean $wc are wildcards allowed? * @return array list of words in the text + * * @author Tom N Harris * @author Andreas Gohr */ @@ -676,6 +687,7 @@ class Doku_Indexer { * * @param array $tokens list of words to search for * @return array list of page names with usage counts + * * @author Tom N Harris * @author Andreas Gohr */ @@ -730,6 +742,7 @@ class Doku_Indexer { * @param string $value search term to look for, must be a string or array of strings * @param callback $func comparison function * @return array lists with page names, keys are query values if $value is array + * * @author Tom N Harris * @author Michael Hamann */ @@ -829,6 +842,7 @@ class Doku_Indexer { * @param array $words The query terms. * @param array $result Set to word => array("length*id" ...) * @return array Set to length => array(id ...) + * * @author Tom N Harris */ protected function getIndexWords(&$words, &$result) { @@ -909,6 +923,7 @@ class Doku_Indexer { * * @param string $key list only pages containing the metadata key (optional) * @return array list of page names + * * @author Tom N Harris */ public function getPages($key=null) { @@ -942,6 +957,7 @@ class Doku_Indexer { * @param int $minlen minimum length of words to count * @param string $key metadata key to list. Uses the fulltext index if not given * @return array list of words as the keys and frequency as values + * * @author Tom N Harris */ public function histogram($min=1, $max=0, $minlen=3, $key=null) { @@ -1002,6 +1018,8 @@ class Doku_Indexer { * Lock the indexer. * * @author Tom N Harris + * + * @return bool|string */ protected function lock() { global $conf; @@ -1033,6 +1051,8 @@ class Doku_Indexer { * Release the indexer lock. * * @author Tom N Harris + * + * @return bool */ protected function unlock() { global $conf; @@ -1050,6 +1070,7 @@ class Doku_Indexer { * @param string $idx name of the index * @param string $suffix subpart identifier * @return array list of lines without CR or LF + * * @author Tom N Harris */ protected function getIndex($idx, $suffix) { @@ -1066,6 +1087,7 @@ class Doku_Indexer { * @param string $suffix subpart identifier * @param array $lines list of lines without LF * @return bool If saving succeeded + * * @author Tom N Harris */ protected function saveIndex($idx, $suffix, &$lines) { @@ -1090,6 +1112,7 @@ class Doku_Indexer { * @param string $suffix subpart identifier * @param int $id the line number * @return string a line with trailing whitespace removed + * * @author Tom N Harris */ protected function getIndexKey($idx, $suffix, $id) { @@ -1114,6 +1137,7 @@ class Doku_Indexer { * @param int $id the line number * @param string $line line to write * @return bool If saving succeeded + * * @author Tom N Harris */ protected function saveIndexKey($idx, $suffix, $id, $line) { @@ -1155,6 +1179,7 @@ class Doku_Indexer { * @param string $suffix subpart identifier * @param string $value line to find in the index * @return int|bool line number of the value in the index or false if writing the index failed + * * @author Tom N Harris */ protected function addIndexKey($idx, $suffix, $value) { @@ -1178,6 +1203,8 @@ class Doku_Indexer { * a sorted array of lengths of the words used in the wiki. * * @author YoBoY + * + * @return array */ protected function listIndexLengths() { return idx_listIndexLengths(); @@ -1190,6 +1217,9 @@ class Doku_Indexer { * that there are indices for. * * @author YoBoY + * + * @param array|int $filter + * @return array */ protected function indexLengths($filter) { global $conf; @@ -1216,6 +1246,11 @@ class Doku_Indexer { * Insert or replace a tuple in a line. * * @author Tom N Harris + * + * @param string $line + * @param string $id + * @param int $count + * @return string */ protected function updateTuple($line, $id, $count) { if ($line != ''){ @@ -1237,6 +1272,10 @@ class Doku_Indexer { * * @author Tom N Harris * @author Andreas Gohr + * + * @param array $keys + * @param string $line + * @return array */ protected function parseTuples(&$keys, $line) { $result = array(); @@ -1257,13 +1296,16 @@ class Doku_Indexer { * Sum the counts in a list of tuples. * * @author Tom N Harris + * + * @param string $line + * @return int */ protected function countTuples($line) { $freq = 0; $parts = explode(':', $line); foreach ($parts as $tuple) { if ($tuple === '') continue; - list($pid, $cnt) = explode('*', $tuple); + list(/* $pid */, $cnt) = explode('*', $tuple); $freq += (int)$cnt; } return $freq; @@ -1273,7 +1315,8 @@ class Doku_Indexer { /** * Create an instance of the indexer. * - * @return Doku_Indexer a Doku_Indexer + * @return Doku_Indexer a Doku_Indexer + * * @author Tom N Harris */ function idx_get_indexer() { @@ -1288,6 +1331,7 @@ function idx_get_indexer() { * Returns words that will be ignored. * * @return array list of stop words + * * @author Tom N Harris */ function & idx_get_stopwords() { @@ -1312,7 +1356,8 @@ function & idx_get_stopwords() { * @param string $page name of the page to index * @param boolean $verbose print status messages * @param boolean $force force reindexing even when the index is up to date - * @return boolean the function completed successfully + * @return string|boolean the function completed successfully + * * @author Tom N Harris */ function idx_addPage($page, $verbose=false, $force=false) { @@ -1441,6 +1486,10 @@ function idx_tokenizer($string, $wc=false) { * Read the list of words in an index (if it exists). * * @author Tom N Harris + * + * @param string $idx + * @param string $suffix + * @return array */ function idx_getIndex($idx, $suffix) { global $conf; @@ -1456,6 +1505,8 @@ function idx_getIndex($idx, $suffix) { * a sorted array of lengths of the words used in the wiki. * * @author YoBoY + * + * @return array */ function idx_listIndexLengths() { global $conf; @@ -1510,6 +1561,9 @@ function idx_listIndexLengths() { * that there are indices for. * * @author YoBoY + * + * @param array|int $filter + * @return array */ function idx_indexLengths($filter) { global $conf; @@ -1539,6 +1593,9 @@ function idx_indexLengths($filter) { * not a letter, number, or underscore. * * @author Tom N Harris + * + * @param string $name + * @return string */ function idx_cleanName($name) { $name = utf8_romanize(trim((string)$name)); diff --git a/inc/io.php b/inc/io.php index 27a34b045..bfa394a17 100644 --- a/inc/io.php +++ b/inc/io.php @@ -20,6 +20,7 @@ if(!defined('DOKU_INC')) die('meh.'); * @param string $id - a pageid, the namespace of that id will be tried to deleted * @param string $basedir - the config name of the type to delete (datadir or mediadir usally) * @return bool - true if at least one namespace was deleted + * * @author Andreas Gohr * @author Ben Coburn */ @@ -60,6 +61,11 @@ function io_sweepNS($id,$basedir='datadir'){ * $data[3] rev: The page revision, false for current wiki pages. * * @author Ben Coburn + * + * @param string $file filename + * @param string $id page id + * @param bool|int $rev revision timestamp + * @return string */ function io_readWikiPage($file, $id, $rev=false) { if (empty($rev)) { $rev = false; } @@ -69,7 +75,11 @@ function io_readWikiPage($file, $id, $rev=false) { /** * Callback adapter for io_readFile(). + * * @author Ben Coburn + * + * @param array $data event data + * @return string */ function _io_readWikiPage_action($data) { if (is_array($data) && is_array($data[0]) && count($data[0])===2) { @@ -88,6 +98,10 @@ function _io_readWikiPage_action($data) { * be sure to set $clean to false! * * @author Andreas Gohr + * + * @param string $file filename + * @param bool $clean + * @return string */ function io_readFile($file,$clean=true){ $ret = ''; @@ -108,9 +122,12 @@ function io_readFile($file,$clean=true){ } /** * Returns the content of a .bz2 compressed file as string + * * @author marcel senf + * + * @param string $file filename + * @return string content */ - function bzfile($file){ $bz = bzopen($file,"r"); $str = ''; @@ -138,6 +155,12 @@ function bzfile($file){ * $data[3] rev: The page revision, false for current wiki pages. * * @author Ben Coburn + * + * @param string $file filename + * @param string $content + * @param string $id page id + * @param int|bool $rev timestamp of revision + * @return bool */ function io_writeWikiPage($file, $content, $id, $rev=false) { if (empty($rev)) { $rev = false; } @@ -149,6 +172,9 @@ function io_writeWikiPage($file, $content, $id, $rev=false) { /** * Callback adapter for io_saveFile(). * @author Ben Coburn + * + * @param array $data event data + * @return bool */ function _io_writeWikiPage_action($data) { if (is_array($data) && is_array($data[0]) && count($data[0])===3) { @@ -168,7 +194,11 @@ function _io_writeWikiPage_action($data) { * and bz2 if extension is .bz2 * * @author Andreas Gohr - * @return bool true on success + * + * @param string $file filename path to file + * @param string $content + * @param bool $append + * @return bool true on success, otherwise false */ function io_saveFile($file,$content,$append=false){ global $conf; @@ -221,6 +251,10 @@ function io_saveFile($file,$content,$append=false){ * 2005-10-14 : added regex option -- Christopher Smith * * @author Steven Danz + * + * @param string $file filename + * @param string $badline exact linematch to remove + * @param bool $regex use regexp? * @return bool true on success */ function io_deleteFromFile($file,$badline,$regex=false){ @@ -285,6 +319,8 @@ function io_deleteFromFile($file,$badline,$regex=false){ * the lock is assumed to be stale and the function goes on * * @author Andreas Gohr + * + * @param string $file filename */ function io_lock($file){ global $conf; @@ -311,6 +347,8 @@ function io_lock($file){ * Unlocks a file * * @author Andreas Gohr + * + * @param string $file filename */ function io_unlock($file){ global $conf; @@ -331,6 +369,9 @@ function io_unlock($file){ * $data[1] ns_type: 'pages' or 'media' namespace tree. * * @author Ben Coburn + * + * @param string $id page id + * @param string $ns_type 'pages' or 'media' */ function io_createNamespace($id, $ns_type='pages') { // verify ns_type @@ -365,6 +406,8 @@ function io_createNamespace($id, $ns_type='pages') { * Create the directory needed for the given file * * @author Andreas Gohr + * + * @param string $file file name */ function io_makeFileDir($file){ $dir = dirname($file); @@ -379,6 +422,9 @@ function io_makeFileDir($file){ * @link http://www.php.net/manual/en/function.mkdir.php * @author * @author Andreas Gohr + * + * @param string $target filename + * @return bool|int|string */ function io_mkdir_p($target){ global $conf; @@ -454,6 +500,9 @@ function io_rmdir($path, $removefiles = false) { * This is used when the safemode workaround is enabled * * @author + * + * @param string $dir name of the new directory + * @return false|string */ function io_mkdir_ftp($dir){ global $conf; @@ -488,6 +537,8 @@ function io_mkdir_ftp($dir){ * its path. * * @author Michael Klier + * + * @return false|string path to new directory or false */ function io_mktmpdir() { global $conf; @@ -516,6 +567,13 @@ function io_mktmpdir() { * * @author Andreas Gohr * @author Chris Smith + * + * @param string $url url to download + * @param string $file path to file or directory where to save + * @param bool $useAttachment if true: try to use name of download, uses otherwise $defaultName, false: uses $file as path to file + * @param string $defaultName fallback for if using $useAttachment + * @param int $maxSize maximum file size + * @return bool|string if failed false, otherwise true or the name of the file in the given dir */ function io_download($url,$file,$useAttachment=false,$defaultName='',$maxSize=2097152){ global $conf; @@ -563,6 +621,10 @@ function io_download($url,$file,$useAttachment=false,$defaultName='',$maxSize=20 * * rename() can not overwrite existing files on Windows * this function will use copy/unlink instead + * + * @param string $from + * @param string $to + * @return bool succes or fail */ function io_rename($from,$to){ global $conf; @@ -582,6 +644,11 @@ function io_rename($from,$to){ * Returns the exit code from the process. * * @author Tom N Harris + * + * @param string $cmd + * @param string $input input pipe + * @param string $output output pipe + * @return int exit code from process */ function io_exec($cmd, $input, &$output){ $descspec = array( diff --git a/inc/media.php b/inc/media.php index 7770d3cc9..4ad67369d 100644 --- a/inc/media.php +++ b/inc/media.php @@ -16,6 +16,9 @@ if(!defined('NL')) define('NL',"\n"); * their CSS tags except pagenames won't be links. * * @author Matthias Grimm + * + * @param array $data + * @param string $id */ function media_filesinuse($data,$id){ global $lang; @@ -45,7 +48,7 @@ function media_filesinuse($data,$id){ * @param string $id media id * @param int $auth permission level * @param array $data - * @return bool + * @return false|string */ function media_metasave($id,$auth,$data){ if($auth < AUTH_UPLOAD) return false; @@ -91,6 +94,7 @@ function media_metasave($id,$auth,$data){ * check if a media is external source * * @author Gerrit Uitslag + * * @param string $id the media ID or URL * @return bool */ @@ -103,6 +107,7 @@ function media_isexternal($id){ * Check if a media item is public (eg, external URL or readable by @ALL) * * @author Andreas Gohr + * * @param string $id the media ID or URL * @return bool */ @@ -214,6 +219,7 @@ define('DOKU_MEDIA_EMPTY_NS', 8); * If configured, checks for media references before deletion * * @author Andreas Gohr + * * @param string $id media id * @param int $auth no longer used * @return int One of: 0, @@ -266,9 +272,9 @@ function media_delete($id,$auth){ /** * Handle file uploads via XMLHttpRequest * - * @param string $ns target namespace - * @param int $auth current auth check result - * @return mixed false on error, id of the new file on success + * @param string $ns target namespace + * @param int $auth current auth check result + * @return false|string false on error, id of the new file on success */ function media_upload_xhr($ns,$auth){ if(!checkSecurityToken()) return false; @@ -311,10 +317,11 @@ function media_upload_xhr($ns,$auth){ * * @author Andreas Gohr * @author Michael Klier - * @param string $ns target namespace - * @param int $auth current auth check result - * @param bool|array $file $_FILES member, $_FILES['upload'] if false - * @return mixed false on error, id of the new file on success + * + * @param string $ns target namespace + * @param int $auth current auth check result + * @param bool|array $file $_FILES member, $_FILES['upload'] if false + * @return false|string false on error, id of the new file on success */ function media_upload($ns,$auth,$file=false){ if(!checkSecurityToken()) return false; @@ -358,6 +365,7 @@ function media_upload($ns,$auth,$file=false){ * Using copy, makes sure any setgid bits on the media directory are honored * * @see move_uploaded_file() + * * @param string $from * @param string $to * @return bool @@ -383,14 +391,13 @@ function copy_uploaded_file($from, $to){ * $data[5] move: * * @triggers MEDIA_UPLOAD_FINISH - */ -/** - * @param array $file + * + * @param array $file * @param string $id - * @param bool $ow - * @param int $auth permission level + * @param bool $ow overwrite? + * @param int $auth permission level * @param string $move function name - * @return array|mixed + * @return false|array|string */ function media_save($file, $id, $ow, $auth, $move) { if($auth < AUTH_UPLOAD) { @@ -453,8 +460,12 @@ function media_save($file, $id, $ow, $auth, $move) { } /** - * Callback adapter for media_upload_finish() + * Callback adapter for media_upload_finish() triggered by MEDIA_UPLOAD_FINISH + * * @author Michael Klier + * + * @param array $data event data + * @return false|array|string */ function _media_upload_action($data) { // fixme do further sanity tests of given data? @@ -471,6 +482,14 @@ function _media_upload_action($data) { * @author Andreas Gohr * @author Michael Klier * @author Kate Arzamastseva + * + * @param string $fn_tmp + * @param string $fn + * @param string $id media id + * @param string $imime mime type + * @param bool $overwrite overwrite existing? + * @param string $move function name + * @return array|string */ function media_upload_finish($fn_tmp, $fn, $id, $imime, $overwrite, $move = 'move_uploaded_file') { global $conf; @@ -514,6 +533,7 @@ function media_upload_finish($fn_tmp, $fn, $id, $imime, $overwrite, $move = 'mov * directory * * @author Kate Arzamastseva + * * @param string $id * @return int - revision date */ @@ -557,6 +577,10 @@ function media_saveOldRevision($id){ * @author Andreas Gohr * @link http://www.splitbrain.org/blog/2007-02/12-internet_explorer_facilitates_cross_site_scripting * @fixme check all 26 magic IE filetypes here? + * + * @param string $file path to file + * @param string $mime mimetype + * @return int */ function media_contentcheck($file,$mime){ global $conf; @@ -566,14 +590,14 @@ function media_contentcheck($file,$mime){ $bytes = fread($fh, 256); fclose($fh); if(preg_match('/<(script|a|img|html|body|iframe)[\s>]/i',$bytes)){ - return -3; + return -3; //XSS: possibly malicious content } } } if(substr($mime,0,6) == 'image/'){ $info = @getimagesize($file); if($mime == 'image/gif' && $info[2] != 1){ - return -1; + return -1; // uploaded content did not match the file extension }elseif($mime == 'image/jpeg' && $info[2] != 2){ return -1; }elseif($mime == 'image/png' && $info[2] != 3){ @@ -584,7 +608,7 @@ function media_contentcheck($file,$mime){ global $TEXT; $TEXT = io_readFile($file); if(checkwordblock()){ - return -2; + return -2; //blocked by the spam blacklist } } return 0; @@ -594,6 +618,12 @@ function media_contentcheck($file,$mime){ * Send a notify mail on uploads * * @author Andreas Gohr + * + * @param string $id media id + * @param string $file path to file + * @param string $mime mime type + * @param bool|int $old_rev revision timestamp or false + * @return bool */ function media_notify($id,$file,$mime,$old_rev=false){ global $conf; @@ -605,6 +635,12 @@ function media_notify($id,$file,$mime,$old_rev=false){ /** * List all files in a given Media namespace + * + * @param string $ns + * @param null|int $auth permission level + * @param string $jump id + * @param bool $fullscreenview + * @param bool|string $sort sorting order */ function media_filelist($ns,$auth=null,$jump='',$fullscreenview=false,$sort=false){ global $conf; @@ -747,6 +783,7 @@ function media_tab_files_options(){ * Returns type of sorting for the list of files in media manager * * @author Kate Arzamastseva + * * @return string - sort type */ function _media_get_sort_type() { @@ -757,6 +794,7 @@ function _media_get_sort_type() { * Returns type of listing for the list of files in media manager * * @author Kate Arzamastseva + * * @return string - list type */ function _media_get_list_type() { @@ -788,6 +826,10 @@ function _media_get_display_param($param, $values) { * Prints tab that displays a list of all files * * @author Kate Arzamastseva + * + * @param string $ns + * @param null|int $auth permission level + * @param string $jump item id */ function media_tab_files($ns,$auth=null,$jump='') { global $lang; @@ -804,6 +846,10 @@ function media_tab_files($ns,$auth=null,$jump='') { * Prints tab that displays uploading form * * @author Kate Arzamastseva + * + * @param string $ns + * @param null|int $auth permission level + * @param string $jump item id */ function media_tab_upload($ns,$auth=null,$jump='') { global $lang; @@ -821,6 +867,9 @@ function media_tab_upload($ns,$auth=null,$jump='') { * Prints tab that displays search form * * @author Kate Arzamastseva + * + * @param string $ns + * @param null|int $auth permission level */ function media_tab_search($ns,$auth=null) { global $INPUT; @@ -843,8 +892,8 @@ function media_tab_search($ns,$auth=null) { * * @param string $image media id * @param string $ns - * @param null|int $auth permission level - * @param string|int $rev + * @param null|int $auth permission level + * @param string|int $rev revision timestamp or empty string */ function media_tab_view($image, $ns, $auth=null, $rev='') { global $lang; @@ -910,10 +959,11 @@ function media_tab_history($image, $ns, $auth=null) { /** * Prints mediafile details * - * @param string $image media id - * @param int $auth permission level - * @param int|string $rev revision timestamp or empty string - * @param JpegMeta|bool $meta + * @param string $image media id + * @param int $auth permission level + * @param int|string $rev revision timestamp or empty string + * @param JpegMeta|bool $meta + * * @author Kate Arzamastseva */ function media_preview($image, $auth, $rev='', $meta=false) { @@ -950,8 +1000,8 @@ function media_preview($image, $auth, $rev='', $meta=false) { * @author Kate Arzamastseva * * @param string $image media id - * @param int $auth permission level - * @param string|int $rev revision timestamp, or empty string + * @param int $auth permission level + * @param string|int $rev revision timestamp, or empty string */ function media_preview_buttons($image, $auth, $rev='') { global $lang, $conf; @@ -1003,9 +1053,9 @@ function media_preview_buttons($image, $auth, $rev='') { * @author Kate Arzamastseva * @param string $image * @param int|string $rev - * @param JpegMeta|bool $meta + * @param JpegMeta|bool $meta * @param int $size - * @return array|bool + * @return array|false */ function media_image_preview_size($image, $rev, $meta, $size = 500) { if (!preg_match("/\.(jpe?g|gif|png)$/", $image) || !file_exists(mediaFN($image, $rev))) return false; @@ -1027,9 +1077,9 @@ function media_image_preview_size($image, $rev, $meta, $size = 500) { * * @author Kate Arzamastseva * - * @param array $tags + * @param array $tags array with tags, first existing is returned * @param JpegMeta $meta - * @param string $alt + * @param string $alt alternative value * @return string */ function media_getTag($tags,$meta,$alt=''){ @@ -1045,7 +1095,7 @@ function media_getTag($tags,$meta,$alt=''){ * @author Kate Arzamastseva * * @param JpegMeta $meta - * @return array + * @return array list of tags of the mediafile */ function media_file_tags($meta) { // load the field descriptions @@ -1074,8 +1124,7 @@ function media_file_tags($meta) { * Prints mediafile tags * * @author Kate Arzamastseva - */ -/** + * * @param string $image image id * @param int $auth permission level * @param string|int $rev revision timestamp, or empty string @@ -1104,13 +1153,12 @@ function media_details($image, $auth, $rev='', $meta=false) { * Shows difference between two revisions of file * * @author Kate Arzamastseva - */ -/** + * * @param string $image image id * @param string $ns * @param int $auth permission level * @param bool $fromajax - * @return void|bool|string + * @return false|null|string */ function media_diff($image, $ns, $auth, $fromajax = false) { global $conf; @@ -1170,14 +1218,13 @@ function media_diff($image, $ns, $auth, $fromajax = false) { // trigger event return trigger_event('MEDIA_DIFF', $data, '_media_file_diff', true); - } /** * Callback for media file diff * - * @param $data - * @return bool|void + * @param array $data event data + * @return false|null */ function _media_file_diff($data) { if(is_array($data) && count($data)===6) { @@ -1318,11 +1365,12 @@ function media_file_diff($image, $l_rev, $r_rev, $ns, $auth, $fromajax){ * and slider * * @author Kate Arzamastseva - * @param string $image - * @param int $l_rev revision timestamp, or empty string - * @param int $r_rev revision timestamp, or empty string - * @param array $l_size - * @param array $r_size + * + * @param string $image image id + * @param int $l_rev revision timestamp, or empty string + * @param int $r_rev revision timestamp, or empty string + * @param array $l_size array with width and height + * @param array $r_size array with width and height * @param string $type */ function media_image_diff($image, $l_rev, $r_rev, $l_size, $r_size, $type) { @@ -1355,10 +1403,11 @@ function media_image_diff($image, $l_rev, $r_rev, $l_size, $r_size, $type) { /** * Restores an old revision of a media file * - * @param string $image - * @param int $rev - * @param int $auth + * @param string $image media id + * @param int $rev revision timestamp or empty string + * @param int $auth * @return string - file's id + * * @author Kate Arzamastseva */ function media_restore($image, $rev, $auth){ @@ -1444,10 +1493,10 @@ function media_searchlist($query,$ns,$auth=null,$fullscreen=false,$sort='natural /** * Formats and prints one file in the list * - * @param array $item - * @param int $auth permission level - * @param string $jump item id - * @param bool $display_namespace + * @param array $item + * @param int $auth permission level + * @param string $jump item id + * @param bool $display_namespace */ function media_printfile($item,$auth,$jump,$display_namespace=false){ global $lang; @@ -1524,9 +1573,9 @@ function media_printfile($item,$auth,$jump,$display_namespace=false){ /** * Display a media icon * - * @param $filename - * @param string $size the size subfolder, if not specified 16x16 is used - * @return string + * @param string $filename media id + * @param string $size the size subfolder, if not specified 16x16 is used + * @return string html */ function media_printicon($filename, $size=''){ list($ext) = mimetype(mediaFN($filename),false); @@ -1546,8 +1595,8 @@ function media_printicon($filename, $size=''){ * @author Kate Arzamastseva * * @param array $item - * @param int $auth - * @param bool|string $jump + * @param int $auth permission level + * @param bool|string $jump item id * @param bool $display_namespace */ function media_printfile_thumbs($item,$auth,$jump=false,$display_namespace=false){ @@ -1598,7 +1647,7 @@ function media_printfile_thumbs($item,$auth,$jump=false,$display_namespace=false * Prints a thumbnail and metainfo * * @param array $item - * @param bool $fullscreen + * @param bool $fullscreen */ function media_printimgdetail($item, $fullscreen=false){ // prepare thumbnail @@ -1662,15 +1711,15 @@ function media_printimgdetail($item, $fullscreen=false){ } /** - * Build link based on the current, adding/rewriting - * parameters + * Build link based on the current, adding/rewriting parameters * * @author Kate Arzamastseva + * * @param array|bool $params - * @param string $amp - separator - * @param bool $abs - * @param bool $params_array - * @return string|array - link + * @param string $amp separator + * @param bool $abs absolute url? + * @param bool $params_array return the parmeters array? + * @return string|array - link or link parameters */ function media_managerURL($params=false, $amp='&', $abs=false, $params_array=false) { global $ID; @@ -1703,8 +1752,8 @@ function media_managerURL($params=false, $amp='&', $abs=false, $params_array * @author Kate Arzamastseva * * @param string $ns - * @param int $auth permission level - * @param bool $fullscreen + * @param int $auth permission level + * @param bool $fullscreen */ function media_uploadform($ns, $auth, $fullscreen = false){ global $lang; @@ -1873,6 +1922,9 @@ function media_nstree($ns){ * Prints a media namespace tree item * * @author Andreas Gohr + * + * @param array $item + * @return string html */ function media_nstree_item($item){ global $INPUT; @@ -1896,6 +1948,9 @@ function media_nstree_item($item){ * Prints a media namespace tree item opener * * @author Andreas Gohr + * + * @param array $item + * @return string html */ function media_nstree_li($item){ $class='media level'.$item['level']; @@ -1917,6 +1972,12 @@ function media_nstree_li($item){ * Resizes the given image to the given size * * @author Andreas Gohr + * + * @param string $file filename, path to file + * @param string $ext extension + * @param int $w desired width + * @param int $h desired height + * @return string path to resized or original size if failed */ function media_resize_image($file, $ext, $w, $h=0){ global $conf; @@ -1937,9 +1998,10 @@ function media_resize_image($file, $ext, $w, $h=0){ $local = getCacheName($file,'.media.'.$w.'x'.$h.'.'.$ext); $mtime = @filemtime($local); // 0 if not exists - if( $mtime > filemtime($file) || - media_resize_imageIM($ext,$file,$info[0],$info[1],$local,$w,$h) || - media_resize_imageGD($ext,$file,$info[0],$info[1],$local,$w,$h) ){ + if($mtime > filemtime($file) || + media_resize_imageIM($ext, $file, $info[0], $info[1], $local, $w, $h) || + media_resize_imageGD($ext, $file, $info[0], $info[1], $local, $w, $h) + ) { if(!empty($conf['fperm'])) @chmod($local, $conf['fperm']); return $local; } @@ -1955,6 +2017,12 @@ function media_resize_image($file, $ext, $w, $h=0){ * image because most pics are more interesting in that area (rule of thirds) * * @author Andreas Gohr + * + * @param string $file filename, path to file + * @param string $ext extension + * @param int $w desired width + * @param int $h desired height + * @return string path to resized or original size if failed */ function media_crop_image($file, $ext, $w, $h=0){ global $conf; @@ -2019,7 +2087,7 @@ function media_crop_image($file, $ext, $w, $h=0){ * @param string $id id of the image * @param int $w resize/crop width * @param int $h resize/crop height - * @return string + * @return string token or empty string if no token required */ function media_get_token($id,$w,$h){ // token is only required for modified images @@ -2042,6 +2110,11 @@ function media_get_token($id,$w,$h){ * * @author Andreas Gohr * @author Pavel Vitis + * + * @param string $url + * @param string $ext extension + * @param int $cache cachetime in seconds + * @return false|string path to cached file */ function media_get_from_URL($url,$ext,$cache){ global $conf; @@ -2054,12 +2127,12 @@ function media_get_from_URL($url,$ext,$cache){ $mtime = @filemtime($local); // 0 if not exists //decide if download needed: - if( ($mtime == 0) || // cache does not exist - ($cache != -1 && $mtime < time()-$cache) // 'recache' and cache has expired - ){ - if(media_image_download($url,$local)){ + if(($mtime == 0) || // cache does not exist + ($cache != -1 && $mtime < time() - $cache) // 'recache' and cache has expired + ) { + if(media_image_download($url, $local)) { return $local; - }else{ + } else { return false; } } @@ -2075,6 +2148,10 @@ function media_get_from_URL($url,$ext,$cache){ * Download image files * * @author Andreas Gohr + * + * @param string $url + * @param string $file path to file in which to put the downloaded content + * @return bool */ function media_image_download($url,$file){ global $conf; @@ -2110,6 +2187,15 @@ function media_image_download($url,$file){ * * @author Pavel Vitis * @author Andreas Gohr + * + * @param string $ext extension + * @param string $from filename path to file + * @param int $from_w original width + * @param int $from_h original height + * @param string $to path to resized file + * @param int $to_w desired width + * @param int $to_h desired height + * @return bool */ function media_resize_imageIM($ext,$from,$from_w,$from_h,$to,$to_w,$to_h){ global $conf; @@ -2134,6 +2220,17 @@ function media_resize_imageIM($ext,$from,$from_w,$from_h,$to,$to_w,$to_h){ * crop images using external ImageMagick convert program * * @author Andreas Gohr + * + * @param string $ext extension + * @param string $from filename path to file + * @param int $from_w original width + * @param int $from_h original height + * @param string $to path to resized file + * @param int $to_w desired width + * @param int $to_h desired height + * @param int $ofs_x offset of crop centre + * @param int $ofs_y offset of crop centre + * @return bool */ function media_crop_imageIM($ext,$from,$from_w,$from_h,$to,$to_w,$to_h,$ofs_x,$ofs_y){ global $conf; @@ -2159,6 +2256,17 @@ function media_crop_imageIM($ext,$from,$from_w,$from_h,$to,$to_w,$to_h,$ofs_x,$o * * @author Andreas Gohr * @author Sebastian Wienecke + * + * @param string $ext extension + * @param string $from filename path to file + * @param int $from_w original width + * @param int $from_h original height + * @param string $to path to resized file + * @param int $to_w desired width + * @param int $to_h desired height + * @param int $ofs_x offset of crop centre + * @param int $ofs_y offset of crop centre + * @return bool */ function media_resize_imageGD($ext,$from,$from_w,$from_h,$to,$to_w,$to_h,$ofs_x=0,$ofs_y=0){ global $conf; @@ -2261,9 +2369,9 @@ function media_resize_imageGD($ext,$from,$from_w,$from_h,$to,$to_w,$to_h,$ofs_x= * Return other media files with the same base name * but different extensions. * - * @param string $src - ID of media file - * @param array $exts - alternative extensions to find other files for - * @return array - mime type => file ID + * @param string $src - ID of media file + * @param string[] $exts - alternative extensions to find other files for + * @return array - array(mime type => file ID) * * @author Anika Henke */ @@ -2288,7 +2396,7 @@ function media_alternativefiles($src, $exts){ * Check if video/audio is supported to be embedded. * * @param string $mime - mimetype of media file - * @param string $type - type of media files to check ('video', 'audio', or none) + * @param string $type - type of media files to check ('video', 'audio', or null for all) * @return boolean * * @author Anika Henke diff --git a/inc/pageutils.php b/inc/pageutils.php index adfb10cc7..b9c6418e2 100644 --- a/inc/pageutils.php +++ b/inc/pageutils.php @@ -20,7 +20,7 @@ * * @param string $param the $_REQUEST variable name, default 'id' * @param bool $clean if true, ID is cleaned - * @return mixed|string + * @return string */ function getID($param='id',$clean=true){ /** @var Input $INPUT */ @@ -97,6 +97,7 @@ function getID($param='id',$clean=true){ * converted to unaccented ones * * @author Andreas Gohr + * * @param string $raw_id The pageid to clean * @param boolean $ascii Force ASCII * @return string cleaned id @@ -152,7 +153,7 @@ function cleanID($raw_id,$ascii=false){ * @author Andreas Gohr * * @param string $id - * @return string|bool the namespace part or false if the given ID has no namespace (root) + * @return string|false the namespace part or false if the given ID has no namespace (root) */ function getNS($id){ $pos = strrpos((string)$id,':'); @@ -435,7 +436,7 @@ function localeFN($id,$ext='txt'){ * @param string $ns namespace which is context of id * @param string $id relative id * @param bool $clean flag indicating that id should be cleaned - * @return mixed|string + * @return string */ function resolve_id($ns,$id,$clean=true){ global $conf; @@ -718,6 +719,7 @@ function utf8_decodeFN($file){ * Used for sidebars, but can be used other stuff as well * * @todo add event hook + * * @param string $page the pagename you're looking for * @return string|false the full page id of the found page, false if any */ diff --git a/inc/parser/handler.php b/inc/parser/handler.php index a1040d12e..0e7b294e5 100644 --- a/inc/parser/handler.php +++ b/inc/parser/handler.php @@ -711,6 +711,9 @@ class Doku_Handler_CallWriter { var $Handler; + /** + * @param Doku_Handler $Handler + */ function Doku_Handler_CallWriter(& $Handler) { $this->Handler = & $Handler; } @@ -747,7 +750,7 @@ class Doku_Handler_Nest { /** * constructor * - * @param object $CallWriter the renderers current call writer + * @param Doku_Handler_CallWriter $CallWriter the renderers current call writer * @param string $close closing instruction name, this is required to properly terminate the * syntax mode if the document ends without a closing pattern */ diff --git a/inc/parser/renderer.php b/inc/parser/renderer.php index 09294539e..6c074e43e 100644 --- a/inc/parser/renderer.php +++ b/inc/parser/renderer.php @@ -190,7 +190,7 @@ class Doku_Renderer extends DokuWiki_Plugin { /** * Render plain text data * - * @param $text + * @param string $text */ function cdata($text) { } @@ -759,6 +759,9 @@ class Doku_Renderer extends DokuWiki_Plugin { * casing and special chars * * @author Andreas Gohr + * + * @param string $name + * @return string */ function _simpleTitle($name) { global $conf; @@ -778,6 +781,11 @@ class Doku_Renderer extends DokuWiki_Plugin { /** * Resolve an interwikilink + * + * @param string $shortcut identifier for the interwiki link + * @param string $reference fragment that refers the content + * @param null|bool $exists reference which returns if an internal page exists + * @return string interwikilink */ function _resolveInterWiki(&$shortcut, $reference, &$exists = null) { //get interwiki URL diff --git a/inc/parser/xhtml.php b/inc/parser/xhtml.php index aa09058df..c17c984d6 100644 --- a/inc/parser/xhtml.php +++ b/inc/parser/xhtml.php @@ -58,10 +58,11 @@ class Doku_Renderer_xhtml extends Doku_Renderer { /** * Register a new edit section range * - * @param $type string The section type identifier - * @param $title string The section title - * @param $start int The byte position for the edit start - * @return string A marker class for the starting HTML element + * @param string $type The section type identifier + * @param string $title The section title + * @param int $start The byte position for the edit start + * @return string A marker class for the starting HTML element + * * @author Adrian Lang */ public function startSectionEdit($start, $type, $title = null) { @@ -72,8 +73,8 @@ class Doku_Renderer_xhtml extends Doku_Renderer { /** * Finish an edit section range * - * @param $end int The byte position for the edit end; null for the rest of - * the page + * @param int $end The byte position for the edit end; null for the rest of the page + * * @author Adrian Lang */ public function finishSectionEdit($end = null) { diff --git a/inc/parserutils.php b/inc/parserutils.php index 9c2a0b570..791033e63 100644 --- a/inc/parserutils.php +++ b/inc/parserutils.php @@ -55,6 +55,11 @@ define('METADATA_RENDER_UNLIMITED', 4); * wasn't found * * @author Andreas Gohr + * + * @param string $id page id + * @param string|int $rev revision timestamp or empty string + * @param bool $excuse + * @return null|string */ function p_wiki_xhtml($id, $rev='', $excuse=true){ $file = wikiFN($id,$rev); @@ -89,6 +94,9 @@ function p_wiki_xhtml($id, $rev='', $excuse=true){ * Returns the specified local text in parsed format * * @author Andreas Gohr + * + * @param string $id page id + * @return null|string */ function p_locale_xhtml($id){ //fetch parsed locale @@ -101,6 +109,11 @@ function p_locale_xhtml($id){ * * @author Andreas Gohr * @author Chris Smith + * + * @param string $file filename, path to file + * @param string $format + * @param string $id page id + * @return null|string */ function p_cached_output($file, $format='xhtml', $id='') { global $conf; @@ -129,6 +142,11 @@ function p_cached_output($file, $format='xhtml', $id='') { * Uses and creates a serialized cache file * * @author Andreas Gohr + * + * @param string $file filename, path to file + * @param bool $cacheonly + * @param string $id page id + * @return array|null */ function p_cached_instructions($file,$cacheonly=false,$id='') { static $run = null; @@ -157,7 +175,8 @@ function p_cached_instructions($file,$cacheonly=false,$id='') { * * @author Harry Fuecks * @author Andreas Gohr - * @param string $text raw wiki syntax text + * + * @param string $text raw wiki syntax text * @return array a list of instruction arrays */ function p_get_instructions($text){ @@ -185,9 +204,9 @@ function p_get_instructions($text){ /** * returns the metadata of a page * - * @param string $id The id of the page the metadata should be returned from - * @param string $key The key of the metdata value that shall be read (by default everything) - separate hierarchies by " " like "date created" - * @param int $render If the page should be rendererd - possible values: + * @param string $id The id of the page the metadata should be returned from + * @param string $key The key of the metdata value that shall be read (by default everything) - separate hierarchies by " " like "date created" + * @param int $render If the page should be rendererd - possible values: * METADATA_DONT_RENDER, METADATA_RENDER_USING_SIMPLE_CACHE, METADATA_RENDER_USING_CACHE * METADATA_RENDER_UNLIMITED (also combined with the previous two options), * default: METADATA_RENDER_USING_CACHE @@ -360,6 +379,9 @@ function p_set_metadata($id, $data, $render=false, $persistent=true){ * used on page deletion * * @author Michael Klier + * + * @param string $id page id + * @return bool success / fail */ function p_purge_metadata($id) { $meta = p_read_metadata($id); @@ -423,6 +445,10 @@ function p_save_metadata($id, $meta) { * renders the metadata of a page * * @author Esther Brunner + * + * @param string $id page id + * @param array $orig the original metadata + * @return array|null array('current'=> array,'persistent'=> array); */ function p_render_metadata($id, $orig){ // make sure the correct ID is in global ID @@ -477,6 +503,8 @@ function p_render_metadata($id, $orig){ * returns all available parser syntax modes in correct order * * @author Andreas Gohr + * + * @return array[] with for each plugin the array('sort' => sortnumber, 'mode' => mode string, 'obj' => plugin object) */ function p_get_parsermodes(){ global $conf; @@ -569,6 +597,10 @@ function p_get_parsermodes(){ * Callback function for usort * * @author Andreas Gohr + * + * @param array $a + * @param array $b + * @return int $a is lower/equal/higher than $b */ function p_sort_modes($a, $b){ if($a['sort'] == $b['sort']) return 0; @@ -582,6 +614,11 @@ function p_sort_modes($a, $b){ * * @author Harry Fuecks * @author Andreas Gohr + * + * @param string $mode + * @param array $instructions + * @param array $info returns render info like enabled toc and cache + * @return null|string rendered output */ function p_render($mode,$instructions,&$info){ if(is_null($instructions)) return ''; @@ -673,8 +710,8 @@ function p_get_renderer($mode) { * METADATA_RENDER_USING_SIMPLE_CACHE, * METADATA_RENDER_USING_CACHE, * METADATA_RENDER_UNLIMITED - * * @return string|null The first heading + * * @author Andreas Gohr * @author Michael Hamann */ @@ -688,8 +725,8 @@ function p_get_first_heading($id, $render=METADATA_RENDER_USING_SIMPLE_CACHE){ * @param string $code source code to be highlighted * @param string $language language to provide highlighting * @param string $wrapper html element to wrap the returned highlighted text - * * @return string xhtml code + * * @author Christopher Smith * @author Andreas Gohr */ diff --git a/inc/plugin.php b/inc/plugin.php index fbfc0325f..8432b21b2 100644 --- a/inc/plugin.php +++ b/inc/plugin.php @@ -48,14 +48,25 @@ class DokuWiki_Plugin { // plugin introspection methods // extract from class name, format = _plugin_[_] + /** + * @return string plugin type + */ function getPluginType() { list($t) = explode('_', get_class($this), 2); return $t; } + + /** + * @return string plugin name + */ function getPluginName() { list($t, $p, $n) = explode('_', get_class($this), 4); return $n; } + + /** + * @return string component name + */ function getPluginComponent() { list($t, $p, $n, $c) = explode('_', get_class($this), 4); return (isset($c)?$c:''); @@ -91,9 +102,11 @@ class DokuWiki_Plugin { } /** - * localFN($id) - * prepends appropriate path for a language dependent filename + * Prepends appropriate path for a language dependent filename * plugin equivalent of localFN() + * + * @param string $id id of localization file + * @return string wiki text */ function localFN($id) { global $conf; @@ -110,9 +123,8 @@ class DokuWiki_Plugin { } /** - * setupLocale() - * reads all the plugins language dependent strings into $this->lang - * this function is automatically called by getLang() + * Reads all the plugins language dependent strings into $this->lang + * this function is automatically called by getLang() */ function setupLocale() { if ($this->localised) return; @@ -196,8 +208,7 @@ class DokuWiki_Plugin { * * @param string $name name of plugin to load * @param bool $msg if a message should be displayed in case the plugin is not available - * - * @return object helper plugin object + * @return DokuWiki_Plugin|null helper plugin object */ function loadHelper($name, $msg = true){ $obj = plugin_load('helper',$name); @@ -211,6 +222,12 @@ class DokuWiki_Plugin { /** * email * standardised function to generate an email link according to obfuscation settings + * + * @param string $email + * @param string $name + * @param string $class + * @param string $more + * @return string html */ function email($email, $name='', $class='', $more='') { if (!$email) return $name; @@ -223,6 +240,13 @@ class DokuWiki_Plugin { /** * external_link * standardised function to generate an external link according to conf settings + * + * @param string $link + * @param string $title + * @param string $class + * @param string $target + * @param string $more + * @return string */ function external_link($link, $title='', $class='', $target='', $more='') { global $conf; @@ -247,8 +271,9 @@ class DokuWiki_Plugin { * Instead use render_text() * * @deprecated 2014-01-22 - * @param $name - * @param $arguments + * + * @param string $name + * @param array $arguments * @return null|string */ function __call($name, $arguments) { @@ -265,7 +290,7 @@ class DokuWiki_Plugin { * output text string through the parser, allows dokuwiki markup to be used * very ineffecient for small pieces of data - try not to use * - * @param string $text wiki markup to parse + * @param string $text wiki markup to parse * @param string $format output format * @return null|string */ diff --git a/inc/plugincontroller.class.php b/inc/plugincontroller.class.php index 86c10585e..21d227ee4 100644 --- a/inc/plugincontroller.class.php +++ b/inc/plugincontroller.class.php @@ -114,7 +114,7 @@ class Doku_Plugin_Controller { * Whether plugin is disabled * * @param string $plugin name of plugin - * @return bool; true disabled, false enabled + * @return bool true disabled, false enabled */ public function isdisabled($plugin) { return empty($this->tmp_plugins[$plugin]); @@ -124,7 +124,7 @@ class Doku_Plugin_Controller { * Disable the plugin * * @param string $plugin name of plugin - * @return bool; true saving succeed, false saving failed + * @return bool true saving succeed, false saving failed */ public function disable($plugin) { if(array_key_exists($plugin,$this->plugin_cascade['protected'])) return false; @@ -136,7 +136,7 @@ class Doku_Plugin_Controller { * Enable the plugin * * @param string $plugin name of plugin - * @return bool; true saving succeed, false saving failed + * @return bool true saving succeed, false saving failed */ public function enable($plugin) { if(array_key_exists($plugin,$this->plugin_cascade['protected'])) return false; @@ -227,7 +227,7 @@ class Doku_Plugin_Controller { * @param bool $forceSave; * false to save only when config changed * true to always save - * @return bool; true saving succeed, false saving failed + * @return bool true saving succeed, false saving failed */ protected function saveList($forceSave = false) { global $conf; @@ -300,12 +300,9 @@ class Doku_Plugin_Controller { /** * Returns a list of available plugin components of given type * - * @param string $type, plugin_type name; - * the type of plugin to return, - * @param bool $enabled; - * true to return enabled plugins, - * false to return disabled plugins - * + * @param string $type plugin_type name; the type of plugin to return, + * @param bool $enabled true to return enabled plugins, + * false to return disabled plugins * @return array of plugin components of requested type */ protected function _getListByType($type, $enabled) { diff --git a/inc/remote.php b/inc/remote.php index a21ef1e25..861353a19 100644 --- a/inc/remote.php +++ b/inc/remote.php @@ -60,6 +60,9 @@ class RemoteAPI { private $dateTransformation; private $fileTransformation; + /** + * constructor + */ public function __construct() { $this->dateTransformation = array($this, 'dummyTransformation'); $this->fileTransformation = array($this, 'dummyTransformation'); @@ -75,7 +78,7 @@ class RemoteAPI { } /** - * call a method via remote api. + * Call a method via remote api. * * @param string $method name of the method to call. * @param array $args arguments to pass to the given method @@ -95,11 +98,25 @@ class RemoteAPI { return $this->callCustomCallPlugin($method, $args); } + /** + * Check existance of core methods + * + * @param string $name name of the method + * @return bool if method exists + */ private function coreMethodExist($name) { $coreMethods = $this->getCoreMethods(); return array_key_exists($name, $coreMethods); } + /** + * Try to call custom methods provided by plugins + * + * @param string $method name of method + * @param array $args + * @return mixed + * @throws RemoteException if method not exists + */ private function callCustomCallPlugin($method, $args) { $customCalls = $this->getCustomCallPlugins(); if (!array_key_exists($method, $customCalls)) { @@ -109,6 +126,12 @@ class RemoteAPI { return $this->callPlugin($customCall[0], $customCall[1], $args); } + /** + * Returns plugin calls that are registered via RPC_CALL_ADD action + * + * @return array with pairs of custom plugin calls + * @triggers RPC_CALL_ADD + */ private function getCustomCallPlugins() { if ($this->pluginCustomCalls === null) { $data = array(); @@ -118,6 +141,15 @@ class RemoteAPI { return $this->pluginCustomCalls; } + /** + * Call a plugin method + * + * @param string $pluginName + * @param string $method method name + * @param array $args + * @return mixed return of custom method + * @throws RemoteException + */ private function callPlugin($pluginName, $method, $args) { $plugin = plugin_load('remote', $pluginName); $methods = $this->getPluginMethods(); @@ -129,6 +161,14 @@ class RemoteAPI { return call_user_func_array(array($plugin, $name), $args); } + /** + * Call a core method + * + * @param string $method name of method + * @param array $args + * @return mixed + * @throws RemoteException if method not exist + */ private function callCoreMethod($method, $args) { $coreMethods = $this->getCoreMethods(); $this->checkAccess($coreMethods[$method]); @@ -139,6 +179,11 @@ class RemoteAPI { return call_user_func_array(array($this->coreMethods, $this->getMethodName($coreMethods, $method)), $args); } + /** + * Check if access should be checked + * + * @param array $methodMeta data about the method + */ private function checkAccess($methodMeta) { if (!isset($methodMeta['public'])) { $this->forceAccess(); @@ -149,12 +194,26 @@ class RemoteAPI { } } - private function checkArgumentLength($method, $args) { - if (count($method['args']) < count($args)) { + /** + * Check the number of parameters + * + * @param array $methodMeta data about the method + * @param array $args + * @throws RemoteException if wrong parameter count + */ + private function checkArgumentLength($methodMeta, $args) { + if (count($methodMeta['args']) < count($args)) { throw new RemoteException('Method does not exist - wrong parameter count.', -32603); } } + /** + * Determine the name of the real method + * + * @param array $methodMeta list of data of the methods + * @param string $method name of method + * @return string + */ private function getMethodName($methodMeta, $method) { if (isset($methodMeta[$method]['name'])) { return $methodMeta[$method]['name']; @@ -164,6 +223,8 @@ class RemoteAPI { } /** + * Perform access check for current user + * * @return bool true if the current user has access to remote api. */ public function hasAccess() { @@ -186,8 +247,10 @@ class RemoteAPI { } /** - * @throws RemoteException On denied access. + * Requests access + * * @return void + * @throws RemoteException On denied access. */ public function forceAccess() { if (!$this->hasAccess()) { @@ -196,7 +259,10 @@ class RemoteAPI { } /** + * Collects all the methods of the enabled Remote Plugins + * * @return array all plugin methods. + * @throws RemoteException if not implemented */ public function getPluginMethods() { if ($this->pluginMethods === null) { @@ -204,6 +270,7 @@ class RemoteAPI { $plugins = plugin_list('remote'); foreach ($plugins as $pluginName) { + /** @var DokuWiki_Remote_Plugin $plugin */ $plugin = plugin_load('remote', $pluginName); if (!is_subclass_of($plugin, 'DokuWiki_Remote_Plugin')) { throw new RemoteException("Plugin $pluginName does not implement DokuWiki_Remote_Plugin"); @@ -219,6 +286,8 @@ class RemoteAPI { } /** + * Collects all the core methods + * * @param RemoteAPICore $apiCore this parameter is used for testing. Here you can pass a non-default RemoteAPICore * instance. (for mocking) * @return array all core methods. @@ -234,22 +303,50 @@ class RemoteAPI { return $this->coreMethods->__getRemoteInfo(); } + /** + * Transform file to xml + * + * @param mixed $data + * @return mixed + */ public function toFile($data) { return call_user_func($this->fileTransformation, $data); } + /** + * Transform date to xml + * + * @param mixed $data + * @return mixed + */ public function toDate($data) { return call_user_func($this->dateTransformation, $data); } + /** + * A simple transformation + * + * @param mixed $data + * @return mixed + */ public function dummyTransformation($data) { return $data; } + /** + * Set the transformer function + * + * @param callback $dateTransformation + */ public function setDateTransformation($dateTransformation) { $this->dateTransformation = $dateTransformation; } + /** + * Set the transformer function + * + * @param callback $fileTransformation + */ public function setFileTransformation($fileTransformation) { $this->fileTransformation = $fileTransformation; } diff --git a/inc/search.php b/inc/search.php index 79d930149..935969d3f 100644 --- a/inc/search.php +++ b/inc/search.php @@ -134,6 +134,11 @@ function search_namespaces(&$data,$base,$file,$type,$lvl,$opts){ /** * List all mediafiles in a namespace + * $opts['depth'] recursion level, 0 for all + * $opts['showmsg'] shows message if invalid media id is used + * $opts['skipacl'] skip acl checking + * $opts['pattern'] check given pattern + * $opts['hash'] add hashes to result list * * @author Andreas Gohr */ diff --git a/inc/subscription.php b/inc/subscription.php index bad98cf6c..58376f2ec 100644 --- a/inc/subscription.php +++ b/inc/subscription.php @@ -444,11 +444,11 @@ class Subscription { * Send the diff for some media change * * @fixme this should embed thumbnails of images in HTML version + * * @param string $subscriber_mail The target mail address * @param string $template Mail template ('uploadmail', ...) * @param string $id Media file for which the notification is * @param int|bool $rev Old revision if any - * @return bool true if successfully sent */ public function send_media_diff($subscriber_mail, $template, $id, $rev = false) { global $conf; @@ -619,6 +619,7 @@ class Subscription { /** * Get a valid message id for a certain $id and revision (or the current revision) + * * @param string $id The id of the page (or media file) the message id should be for * @param string $rev The revision of the page, set to the current revision of the page $id if not set * @return string diff --git a/inc/template.php b/inc/template.php index 49f6986fd..98ea9df82 100644 --- a/inc/template.php +++ b/inc/template.php @@ -68,6 +68,7 @@ function tpl_basedir($tpl='') { * handled by this function. ACL stuff is not done here either. * * @author Andreas Gohr + * * @triggers TPL_ACT_RENDER * @triggers TPL_CONTENT_DISPLAY * @param bool $prependTOC should the TOC be displayed here? @@ -186,6 +187,7 @@ function tpl_content_core() { * a false argument * * @author Andreas Gohr + * * @param bool $return Should the TOC be returned instead to be printed? * @return string */ @@ -243,6 +245,8 @@ function tpl_toc($return = false) { * Handle the admin page contents * * @author Andreas Gohr + * + * @return bool */ function tpl_admin() { global $INFO; @@ -277,6 +281,7 @@ function tpl_admin() { * This has to go into the head section of your template. * * @author Andreas Gohr + * * @triggers TPL_METAHEADER_OUTPUT * @param bool $alt Should feeds and alternative format links be added? * @return bool @@ -426,10 +431,12 @@ function tpl_metaheaders($alt = true) { * instances. Attributes are given as key value pairs. Values will be HTML * encoded automatically so they should be provided as is in the $data array. * - * For tags having a body attribute specify the the body data in the special + * For tags having a body attribute specify the body data in the special * attribute '_data'. This field will NOT BE ESCAPED automatically. * * @author Andreas Gohr + * + * @param array $data */ function _tpl_metaheaders_action($data) { foreach($data as $tag => $inst) { @@ -456,6 +463,12 @@ function _tpl_metaheaders_action($data) { * Just builds a link. * * @author Andreas Gohr + * + * @param string $url + * @param string $name + * @param string $more + * @param bool $return return html + * @return bool|string html or true */ function tpl_link($url, $name, $more = '', $return = false) { $out = ' + * + * @param string $id page id + * @param string|null $name the name of the link + * @return bool */ function tpl_pagelink($id, $name = null) { print ''.html_wikilink($id, $name).''; @@ -485,6 +502,9 @@ function tpl_pagelink($id, $name = null) { * returns false if none is available * * @author Andreas Gohr + * + * @param string $id page id + * @return false|string */ function tpl_getparent($id) { $parent = getNS($id).':'; @@ -539,7 +559,7 @@ function tpl_button($type, $return = false) { * @author Adrian Lang * @see tpl_get_action * - * @param string $type + * @param string $type action command * @param string $pre prefix of link * @param string $suf suffix of link * @param string $inner innerHML of link @@ -767,7 +787,8 @@ function tpl_get_action($type) { * Wrapper around tpl_button() and tpl_actionlink() * * @author Anika Henke - * @param + * + * @param string $type action command * @param bool $link link or form button? * @param string|bool $wrapper HTML element wrapper * @param bool $return return or print @@ -801,6 +822,7 @@ function tpl_action($type, $link = false, $wrapper = false, $return = false, $pr * autocompletion feature (MSIE and Firefox) * * @author Andreas Gohr + * * @param bool $ajax * @param bool $autocomplete * @return bool @@ -829,6 +851,7 @@ function tpl_searchform($ajax = true, $autocomplete = true) { * Print the breadcrumbs trace * * @author Andreas Gohr + * * @param string $sep Separator between entries * @return bool */ @@ -870,6 +893,7 @@ function tpl_breadcrumbs($sep = '•') { * @author Sean Coates * @author * @todo May behave strangely in RTL languages + * * @param string $sep Separator between entries * @return bool */ @@ -920,6 +944,7 @@ function tpl_youarehere($sep = ' » ') { * Could be enhanced with a profile link in future? * * @author Andreas Gohr + * * @return bool */ function tpl_userinfo() { @@ -938,6 +963,7 @@ function tpl_userinfo() { * Print some info about the current page * * @author Andreas Gohr + * * @param bool $ret return content instead of printing it * @return bool|string */ @@ -1001,6 +1027,7 @@ function tpl_pageinfo($ret = false) { * the given ID is used. * * @author Andreas Gohr + * * @param string $id page id * @param bool $ret return content instead of printing * @return bool|string @@ -1038,6 +1065,7 @@ function tpl_pagetitle($id = null, $ret = false) { * Only allowed in: detail.php * * @author Andreas Gohr + * * @param array $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 @@ -1128,7 +1156,7 @@ function tpl_get_img_meta() { * @param $maxheight int - maximal height of the image * @param $link bool - link to the orginal size? * @param $params array - additional image attributes - * @return mixed Result of TPL_IMG_DISPLAY + * @return bool Result of TPL_IMG_DISPLAY */ function tpl_img($maxwidth = 0, $maxheight = 0, $link = true, $params = null) { global $IMG; @@ -1280,6 +1308,9 @@ function tpl_loadConfig() { * tpl_getLang($id) * * use this function to access template language variables + * + * @param string $id key of language string + * @return string */ function tpl_getLang($id) { static $lang = array(); @@ -1311,6 +1342,9 @@ function tpl_locale_xhtml($id) { /** * Prepends appropriate path for a language dependent filename + * + * @param string $id id of localized text + * @return string wiki text */ function tpl_localeFN($id) { $path = tpl_incdir().'lang/'; @@ -1337,6 +1371,8 @@ function tpl_localeFN($id) { * * @triggers MEDIAMANAGER_CONTENT_OUTPUT * @param bool $fromajax - set true when calling this function via ajax + * @param string $sort + * @author Andreas Gohr */ function tpl_mediaContent($fromajax = false, $sort='natural') { @@ -1511,6 +1547,9 @@ function tpl_mediaTree() { * Note: this will not use any pretty URLs * * @author Andreas Gohr + * + * @param string $empty empty option label + * @param string $button submit button label */ function tpl_actiondropdown($empty = '', $button = '>') { global $ID; @@ -1737,10 +1776,11 @@ function tpl_flush() { * If a given location starts with a colon it is assumed to be a media * file, otherwise it is assumed to be relative to the current template * - * @param array $search locations to look at - * @param bool $abs if to use absolute URL - * @param array &$imginfo filled with getimagesize() + * @param string[] $search locations to look at + * @param bool $abs if to use absolute URL + * @param array &$imginfo filled with getimagesize() * @return string + * * @author Andreas Gohr */ function tpl_getMediaFile($search, $abs = false, &$imginfo = null) { @@ -1791,6 +1831,8 @@ function tpl_getMediaFile($search, $abs = false, &$imginfo = null) { * * @author Anika Henke * @author Andreas Gohr + * + * @param string $file */ function tpl_includeFile($file) { global $config_cascade; @@ -1816,6 +1858,7 @@ function tpl_includeFile($file) { * Returns tag for various icon types (favicon|mobile|generic) * * @author Anika Henke + * * @param array $types - list of icon types to display (favicon|mobile|generic) * @return string */ @@ -1891,6 +1934,8 @@ function tpl_media() { * Return useful layout classes * * @author Anika Henke + * + * @return string */ function tpl_classes() { global $ACT, $conf, $ID, $INFO; diff --git a/lib/exe/xmlrpc.php b/lib/exe/xmlrpc.php index c09daa17c..3a878ebe4 100644 --- a/lib/exe/xmlrpc.php +++ b/lib/exe/xmlrpc.php @@ -40,10 +40,18 @@ class dokuwiki_xmlrpc_server extends IXR_Server { } } + /** + * @param string|int $data iso date(yyyy[-]mm[-]dd[ hh:mm[:ss]]) or timestamp + * @return IXR_Date + */ function toDate($data) { return new IXR_Date($data); } + /** + * @param string $data + * @return IXR_Base64 + */ function toFile($data) { return new IXR_Base64($data); } diff --git a/lib/plugins/acl/remote.php b/lib/plugins/acl/remote.php index 2fdc697db..b10c544ee 100644 --- a/lib/plugins/acl/remote.php +++ b/lib/plugins/acl/remote.php @@ -1,7 +1,16 @@ array( 'args' => array('string','string','int'), @@ -17,13 +26,28 @@ class remote_plugin_acl extends DokuWiki_Remote_Plugin { ); } - function addAcl($scope, $user, $level){ + /** + * Add a new entry to ACL config + * + * @param string $scope + * @param string $user + * @param int $level see also inc/auth.php + * @return bool + */ + public function addAcl($scope, $user, $level){ /** @var admin_plugin_acl $apa */ $apa = plugin_load('admin', 'acl'); return $apa->_acl_add($scope, $user, $level); } - function delAcl($scope, $user){ + /** + * Remove an entry from ACL config + * + * @param string $scope + * @param string $user + * @return bool + */ + public function delAcl($scope, $user){ /** @var admin_plugin_acl $apa */ $apa = plugin_load('admin', 'acl'); return $apa->_acl_del($scope, $user); -- cgit v1.2.3