diff --git a/bin/gittool.php b/bin/gittool.php
index 6944dde57c1ee70aab66762c80621538c41c4698..7991a9997c9e822d01982d6e04f9890afe515d6e 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 8fc4ba74ff7d25bdafeced20ccfb69db9ea3e0e4..54bfd47558a76452464a8fb5d86f707cc9c1ec09 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 3c955cf88dd48ade31256835918d0e28d2060ab3..210d1c0eb9a0ecc84108eedb8efd3b7cfe9705db 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 ea20e3e568334cc8e4aecedadc14fb9bafaba2c1..2e991b52fabf00e02328ac020366e65ae588a99c 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 <andi@splitbrain.org>
*/
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 <andi@splitbrain.org>
*/
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 <andi@splitbrain.org>
*/
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 <cpuidle@gmx.de>
* @author Andreas Gohr <andi@splitbrain.org>
*/
@@ -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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
function _readLine($socket, $message) {
@@ -729,6 +735,9 @@ class HTTPClient {
* Uses _debug_text or _debug_html depending on the SAPI name
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 '<b>'.$info.'</b> '.($this->_time() - $this->start).'s<br />';
@@ -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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @param array $headers
+ * @return string
*/
function _buildHeaders($headers){
$string = '';
@@ -824,6 +841,8 @@ class HTTPClient {
* get cookies as http header string
*
* @author Andreas Goetz <cpuidle@gmx.de>
+ *
+ * @return string
*/
function _getCookies(){
$headers = '';
@@ -839,6 +858,9 @@ class HTTPClient {
* Encode data for posting
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @param array $data
+ * @return string
*/
function _postMultipartEncode($data){
$boundary = '--'.$this->boundary;
diff --git a/inc/IXR_Library.php b/inc/IXR_Library.php
index 2becf4a541d13f2fc0eeb167c28db2796ea91435..6ec39789436b60f22fe62656b272f7a0bc2a53e7 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 94da2a10efdc25af5a8d45f8e3c2309b5c1a287f..f4a4612dfaddc70103dbc7a44294a9d94243fddd 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 3b6c6694cd4efe1daa749d0c778a80e058eac1d0..d50bad9b725636a35b96d608a3ba920533949f27 100644
--- a/inc/JpegMeta.php
+++ b/inc/JpegMeta.php
@@ -133,6 +133,9 @@ class JpegMeta {
* through one function
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
* @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 <joe.lapp@pobox.com>
+ *
+ * @return string
*/
function getShutterSpeed() {
if (!isset($this->_info['exif'])) {
@@ -275,6 +295,9 @@ class JpegMeta {
* Return an EXIF field
*
* @author Sebastian Delmont <sdelmont@zonageek.com>
+ *
+ * @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 <hakan.sandell@mydata.se>
+ *
+ * @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 <sdelmont@zonageek.com>
+ *
+ * @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 <sdelmont@zonageek.com>
+ *
+ * @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 <sdelmont@zonageek.com>
* @author Joe Lapp <joe.lapp@pobox.com>
+ *
+ * @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 <sdelmont@zonageek.com>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <sdelmont@zonageek.com>
+ *
+ * @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 <sdelmont@zonageek.com>
+ *
+ * @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 <sdelmont@zonageek.com>
+ *
+ * @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 <sdelmont@zonageek.com>
+ *
+ * @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 <andi@splitbrain.org>
*/
@@ -556,6 +613,8 @@ class JpegMeta {
* Gather various date fields
*
* @author Sebastian Delmont <sdelmont@zonageek.com>
+ *
+ * @return array|bool
*/
function getDates() {
$this->_parseAll();
@@ -692,6 +751,8 @@ class JpegMeta {
* Get the image width, tries various fields
*
* @author Sebastian Delmont <sdelmont@zonageek.com>
+ *
+ * @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 <sdelmont@zonageek.com>
+ *
+ * @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 <sdelmont@zonageek.com>
+ *
+ * @return false|string
*/
function getDimStr() {
if ($this->_markers == null) {
@@ -766,6 +831,9 @@ class JpegMeta {
* Checks for an embedded thumbnail
*
* @author Sebastian Delmont <sdelmont@zonageek.com>
+ *
+ * @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 <sdelmont@zonageek.com>
+ *
+ * @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 <sdelmont@zonageek.com>
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 fb9ed460c0cc2b32c2bbc7d419eae1ee1ae25b83..087d82c99efc85ab88fe720e1b598def7d70dcd2 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öö <foo@bar.com>, 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 db6a3a77cc231e88017a136726214ffb5a5cf4f3..15f896dcff09cbd305ae15dca680f35668d82897 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 <andi@splitbrain.org>
- * @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 <andi@splitbrain.org>
* @author <mikey_nich at hotmail dot com>
* @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 <mikey_nich at hotmail dot com>
* @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 8c7a0e846573e38a58d99a212fd1b16666ebd71b..b34fe7f20c266c8d2cc3b77159b8803534bc5bab 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 <osd@foosel.net>
+ *
* @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 <osd@foosel.net>
+ *
+ * @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 <osd@foosel.net>
+ *
+ * @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 <chi@chimeric.de>
+ *
+ * @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 <chi@chimeric.de>
+ *
+ * @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 <osd@foosel.net>
+ *
+ * @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 <chi@chimeric.de>
+ *
+ * @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 <michael@content-space.de>
* @author Michael Klier <chi@chimeric.de>
+ *
+ * @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 <michael@content-space.de>
* @author Michael Klier <chi@chimeric.de>
+ *
+ * @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 <chi@chimeric.de>
+ *
+ * @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 33f6d7a360d3d390ee16dbf32dbc7706e3b5a619..0325f6d4482c9676f3138622efd02474263d9eea 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 8c7d33fc1d9b6a7ddee2d086f4df6c9becc804b1..05831df58f096dcca64a6fcb467f84b164360363 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 5cf63a6ca016ab4a5f1ae23d09c8a106cb1962a1..68b71a36a2e81c050fab101718395cc4d4601d52 100644
--- a/inc/actions.php
+++ b/inc/actions.php
@@ -221,6 +221,9 @@ function act_sendheaders($headers) {
* Sanitize the action command
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
* @author Michael Klier <chi@chimeric.de>
+ *
+ * @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 <michael@content-space.de>
+ *
+ * @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 <lang@cosmocode.de>
+ *
+ * @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 <lang@cosmocode.de>
+ *
+ * @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 dc2b6cad832aac09c3ae0aba89e56a5401e9cfe2..3a6a2f65a769e8b25dadeb088ebf3e8b76b3afe4 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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
* @return string The auth token
*/
function auth_createToken() {
@@ -351,6 +354,7 @@ function auth_browseruid() {
* and stored in this file.
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
* @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 <michael@content-space.de>
* @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 <michael@content-space.de>
+ *
* @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
* @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 <andi@splitbrain.org>
* @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
* @param array $data event data
* @return int permission level
*/
@@ -832,6 +843,10 @@ function auth_aclcheck_cb($data) {
*
* @author Andreas Gohr <gohr@cosmocode.de>
* @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
* @return bool true on success, false on any error
*/
function register() {
@@ -1280,6 +1297,7 @@ function act_resendpwd() {
* is chosen.
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
* @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 bcf5804a2ffc522de6036dbd42a6e77577cbcd8e..7499515bc2bc79198007c23a79d7dae016c24372 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 8c14f21b06ae980d3eea0967efcfb825e84892b0..e2826e4b3e99628c0b61e31a146eb41cf4f5c07d 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 25bfddf7db7f1afbc14454df05d9c17f176bf216..29d76ece13b2bdb2d91c91a69190b7fc190a49f9 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 91a068bb06562549ab1aa359ed2fd38e817b8a0a..444e901986d582c53505aef75f8671abc6e5de30 100644
--- a/inc/common.php
+++ b/inc/common.php
@@ -49,7 +49,7 @@ function ptln($string, $indent = 0) {
*
* @author Andreas Gohr <andi@splitbrain.org>
*
- * @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 <andi@splitbrain.org>
* @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 <andi@splitbrain.org>
*
* @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 = '<div class="no"><input type="hidden" name="sectok" value="'.getSecurityToken().'" /></div>'."\n";
@@ -336,7 +337,7 @@ function buildAttributes($params, $skipempty = false) {
*
* @author Andreas Gohr <andi@splitbrain.org>
*
- * @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 <andi@splitbrain.org>
@@ -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 <b.martin@cybernet.ch>
@@ -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 31371d41fb5a200f1c845388bed182960e38c0d9..85bf5128ce3fb5a29f6fdc3d75ca841e913da565 100644
--- a/inc/confutils.php
+++ b/inc/confutils.php
@@ -14,6 +14,10 @@
* are returned.
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 318a7617e4aa356152547ab60eae524e364b2297..4cd06b9f99e302580f757fc4c4222a08da6d8219 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 c61c54503a70edbfeb31f0380a3dc2cf8ea5022f..70becc01e13b534058f32b3de269abd7ee1f5064 100644
--- a/inc/fetch.functions.php
+++ b/inc/fetch.functions.php
@@ -16,6 +16,7 @@
* @author Andreas Gohr <andi@splitbrain.org>
* @author Ben Coburn <btcoburn@silicodon.net>
* @author Gerry Weissbach <dokuwiki@gammaproduction.de>
+ *
* @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 <gerry.w@gammaproduction.de>
+ *
* @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 <andi@splitbrain.org>
+ *
+ * @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 fadc71d3e886f95e2f88de8335e03c1bcc322cbb..00eea9b3a084e12c7a36ed2527b18df043237aec 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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html of tag
*/
function form_closetag($attrs) {
return '</'.$attrs['_tag'].'>';
@@ -634,6 +685,9 @@ function form_closetag($attrs) {
* Attributes are passed to buildAttributes()
*
* @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
*/
function form_openfieldset($attrs) {
$s = '<fieldset '.buildAttributes($attrs,true).'>';
@@ -648,6 +702,8 @@ function form_openfieldset($attrs) {
* There are no attributes.
*
* @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @return string html
*/
function form_closefieldset() {
return '</fieldset>';
@@ -661,6 +717,9 @@ function form_closefieldset() {
* Value is passed to formText()
*
* @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
*/
function form_hidden($attrs) {
return '<input type="hidden" name="'.$attrs['name'].'" value="'.formText($attrs['value']).'" />';
@@ -674,6 +733,9 @@ function form_hidden($attrs) {
* Text will be passed to formText(), attributes to buildAttributes()
*
* @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
*/
function form_field($attrs) {
$s = '<label';
@@ -729,6 +797,9 @@ function form_field($attrs) {
* Other attributes are passed to buildAttributes() for the input tag.
*
* @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
*/
function form_fieldright($attrs) {
$s = '<label';
@@ -750,6 +821,9 @@ function form_fieldright($attrs) {
* Other attributes are passed to buildAttributes() for the input tag.
*
* @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 <chi@chimeric.de>
+ *
+ * @param array $attrs attributes
+ * @return string html
*/
function form_filefield($attrs) {
$s = '<label';
@@ -824,6 +904,9 @@ function form_filefield($attrs) {
* $attrs['value'][1] is constructed as well.
*
* @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
*/
function form_listboxfield($attrs) {
$s = '<label';
diff --git a/inc/fulltext.php b/inc/fulltext.php
index c1dc16e4741e543000fec139bfcd717f66aaee6f..d6cddc56654525d96233d10b135dba4ad04538ea 100644
--- a/inc/fulltext.php
+++ b/inc/fulltext.php
@@ -20,6 +20,9 @@ if(!defined('FT_SNIPPET_NUMBER')) define('FT_SNIPPET_NUMBER',15);
*
* refactored into ft_pageSearch(), _ft_pageSearch() and trigger_event()
*
+ * @param string $query
+ * @param array $highlight
+ * @return array
*/
function ft_pageSearch($query,&$highlight){
@@ -35,6 +38,9 @@ function ft_pageSearch($query,&$highlight){
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Kazutaka Miyasaka <kazmiya@gmail.com>
+ *
+ * @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 <andi@splitbrain.org>
* @author Adrian Lang <lang@cosmocode.de>
+ *
+ * @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 <andi@splitbrain.org>
* @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 <kazmiya@gmail.com>
*/
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 <kazmiya@gmail.com>
*/
function ft_resultComplement($args) {
@@ -507,6 +544,10 @@ function ft_resultComplement($args) {
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Kazutaka Miyasaka <kazmiya@gmail.com>
+ *
+ * @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 <kazmiya@gmail.com>
+ *
+ * @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 ce6360175c4afb4f2ac59e43633aece6b733cae3..adcd212edc90ad5037862a01c5d596b3c5311451 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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <lang@cosmocode.de>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
* @author Harry Fuecks <hfuecks@gmail.com>
+ *
+ * @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 <hfuecks@gmail.com>
+ *
+ * @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 <matthiasgrimm@users.sourceforge.net>
* @author Ben Coburn <btcoburn@silicodon.net>
* @author Kate Arzamastseva <pshns@ukr.net>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @param array $item
+ * @return string html
*/
function html_li_default($item){
return '<li class="level'.$item['level'].'">';
@@ -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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @return array|bool
*/
function html_minoredit(){
global $conf;
@@ -2081,6 +2131,9 @@ function html_resendpwd() {
* Return the TOC rendered to XHTML
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
* @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 efeb2a56ca328dda83d6a3d422d718bd8c3c4908..ac79aa1768cb4358b2558401ec8625f8fd379f1d 100644
--- a/inc/httputils.php
+++ b/inc/httputils.php
@@ -15,6 +15,7 @@ define('HTTP_CHUNK_SIZE',16*1024);
*
* @author Simon Willison <swillison@gmail.com>
* @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 <chris@jalakai.co.uk>
+ *
* @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 <chris.eureka@jalakai.co.uk>
+ *
+ * @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 5ca2f0bb1ff327351971b2263299f7ec49d3c698..ec0c523e080d040e9fc9985f40d70553a4ef4c81 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 <tnharris@whoopdedo.org>
* @author Michael Hamann <michael@content-space.de>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
* @author Andreas Gohr <andi@splitbrain.org>
*/
@@ -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 <andi@splitbrain.org>
* @author Christopher Smith <chris@jalakai.co.uk>
* @author Tom N Harris <tnharris@whoopdedo.org>
@@ -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 <tnharris@whoopdedo.org>
* @author Michael Hamann <michael@content-space.de>
*/
@@ -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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
* @author Andreas Gohr <andi@splitbrain.org>
*/
@@ -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 <tnharris@whoopdedo.org>
* @author Andreas Gohr <andi@splitbrain.org>
*/
@@ -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 <tnharris@whoopdedo.org>
* @author Michael Hamann <michael@content-space.de>
*/
@@ -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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
+ *
+ * @return bool|string
*/
protected function lock() {
global $conf;
@@ -1033,6 +1051,8 @@ class Doku_Indexer {
* Release the indexer lock.
*
* @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <yoboy.leguesh@gmail.com>
+ *
+ * @return array
*/
protected function listIndexLengths() {
return idx_listIndexLengths();
@@ -1190,6 +1217,9 @@ class Doku_Indexer {
* that there are indices for.
*
* @author YoBoY <yoboy.leguesh@gmail.com>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
*/
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 <tnharris@whoopdedo.org>
+ *
+ * @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 <yoboy.leguesh@gmail.com>
+ *
+ * @return array
*/
function idx_listIndexLengths() {
global $conf;
@@ -1510,6 +1561,9 @@ function idx_listIndexLengths() {
* that there are indices for.
*
* @author YoBoY <yoboy.leguesh@gmail.com>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 27a34b045957f5e3a6a6be54c983d58be718d98a..bfa394a17c298d4b425691f013211d1bb3a4c024 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 <andi@splitbrain.org>
* @author Ben Coburn <btcoburn@silicodon.net>
*/
@@ -60,6 +61,11 @@ function io_sweepNS($id,$basedir='datadir'){
* $data[3] rev: The page revision, false for current wiki pages.
*
* @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @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 <btcoburn@silicodon.net>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <marcel@rucksackreinigung.de>
+ *
+ * @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 <btcoburn@silicodon.net>
+ *
+ * @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 <btcoburn@silicodon.net>
+ *
+ * @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 <andi@splitbrain.org>
- * @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 <chris@jalakai.co.uk>
*
* @author Steven Danz <steven-danz@kc.rr.com>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @param string $file filename
*/
function io_lock($file){
global $conf;
@@ -311,6 +347,8 @@ function io_lock($file){
* Unlocks a file
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <btcoburn@silicodon.net>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <saint@corenova.com>
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <chi@chimeric.de>
+ *
+ * @return false|string path to new directory or false
*/
function io_mktmpdir() {
global $conf;
@@ -516,6 +567,13 @@ function io_mktmpdir() {
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Chris Smith <chris@jalakai.co.uk>
+ *
+ * @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 <tnharris@whoopdedo.org>
+ *
+ * @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 7770d3cc9b86a3aef2c5c9e550f2a2d5163b8ab2..4ad67369d3b98471549e192e0cacbc06faad1da3 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 <matthiasgrimm@users.sourceforge.net>
+ *
+ * @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 <klapinklapin@gmail.com>
+ *
* @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
* @author Michael Klier <chi@chimeric.de>
- * @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 <chi@chimeric.de>
+ *
+ * @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 <andi@splitbrain.org>
* @author Michael Klier <chi@chimeric.de>
* @author Kate Arzamastseva <pshns@ukr.net>
+ *
+ * @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 <pshns@ukr.net>
+ *
* @param string $id
* @return int - revision date
*/
@@ -557,6 +577,10 @@ function media_saveOldRevision($id){
* @author Andreas Gohr <andi@splitbrain.org>
* @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 <andi@splitbrain.org>
+ *
+ * @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 <pshns@ukr.net>
+ *
* @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 <pshns@ukr.net>
+ *
* @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 <pshns@ukr.net>
+ *
+ * @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 <pshns@ukr.net>
+ *
+ * @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 <pshns@ukr.net>
+ *
+ * @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 <pshns@ukr.net>
*/
function media_preview($image, $auth, $rev='', $meta=false) {
@@ -950,8 +1000,8 @@ function media_preview($image, $auth, $rev='', $meta=false) {
* @author Kate Arzamastseva <pshns@ukr.net>
*
* @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 <pshns@ukr.net>
* @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 <pshns@ukr.net>
*
- * @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 <pshns@ukr.net>
*
* @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 <pshns@ukr.net>
- */
-/**
+ *
* @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 <pshns@ukr.net>
- */
-/**
+ *
* @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 <pshns@ukr.net>
- * @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 <pshns@ukr.net>
*/
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 <pshns@ukr.net>
*
* @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 <pshns@ukr.net>
+ *
* @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 <pshns@ukr.net>
*
* @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
* @author Pavel Vitis <Pavel.Vitis@seznam.cz>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <Pavel.Vitis@seznam.cz>
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
* @author Sebastian Wienecke <s_wienecke@web.de>
+ *
+ * @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 <anika@selfthinker.org>
*/
@@ -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 <anika@selfthinker.org>
diff --git a/inc/pageutils.php b/inc/pageutils.php
index adfb10cc73020540ece22c854beb29f84dbd164f..b9c6418e2520b1b1e85385a86c3ad52939124799 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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
*
* @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 a1040d12e78e21bb77c6c9af3faae21f84d5333e..0e7b294e593b54af45d7caccac97a2d928c52374 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 09294539e4538d5c06fbef02cb5cca0a604e33ae..6c074e43e7f10f5fb7e812eac05f6d2694655e6e 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 <andi@splitbrain.org>
+ *
+ * @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 aa09058df14239b6b251f8bd3a0d8ffac612f3e5..c17c984d6d9f9d11935961fa736e066baf90b1d8 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 <lang@cosmocode.de>
*/
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 <lang@cosmocode.de>
*/
public function finishSectionEdit($end = null) {
diff --git a/inc/parserutils.php b/inc/parserutils.php
index 9c2a0b570fe4886c47dea60c6bc55c8f472b3eec..791033e631cb0752d0ff4a7ae8a3864869a23a45 100644
--- a/inc/parserutils.php
+++ b/inc/parserutils.php
@@ -55,6 +55,11 @@ define('METADATA_RENDER_UNLIMITED', 4);
* wasn't found
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
* @author Chris Smith <chris@jalakai.co.uk>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <hfuecks@gmail.com>
* @author Andreas Gohr <andi@splitbrain.org>
- * @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 <chi@chimeric.de>
+ *
+ * @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 <esther@kaffeehaus.ch>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 <hfuecks@gmail.com>
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
* @author Michael Hamann <michael@content-space.de>
*/
@@ -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 <chris@jalakai.co.uk>
* @author Andreas Gohr <andi@splitbrain.org>
*/
diff --git a/inc/plugin.php b/inc/plugin.php
index fbfc0325f74ed03dbb8f714e35ae34de93af378c..8432b21b260c0195e522a8e603f82ff49b8f6b12 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 type>_plugin_<name>[_<component name>]
+ /**
+ * @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 86c10585e85739b183f01d28d4149ebcbf399912..21d227ee4970858de433538891762f1dcf0822aa 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 a21ef1e2538b4caa5ef8dced4787a3c7995d9f38..861353a190b74fb0d1a4f5e693ee6d5d565e5185 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 79d9301495a04483542a4fdcaaa359a989e5791a..935969d3f2fb2871b79e15c76826e07dddcbbb3b 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 <andi@splitbrain.org>
*/
diff --git a/inc/subscription.php b/inc/subscription.php
index bad98cf6c2d6a5008a25fe50deebf2a19af842dc..58376f2ecd55057adf8d9bdb5404c4af81117cbb 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 49f6986fd8daa74d1e0d61a753a6e9276950242c..98ea9df82c3d78feaea0b01272472bfbf828f271 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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
+ *
+ * @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 = '<a href="'.$url.'" ';
@@ -472,6 +485,10 @@ function tpl_link($url, $name, $more = '', $return = false) {
* Wrapper around html_wikilink
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id page id
+ * @param string|null $name the name of the link
+ * @return bool
*/
function tpl_pagelink($id, $name = null) {
print '<bdi>'.html_wikilink($id, $name).'</bdi>';
@@ -485,6 +502,9 @@ function tpl_pagelink($id, $name = null) {
* returns false if none is available
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @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 <mail@adrianlang.de>
* @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 <anika@selfthinker.org>
- * @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
* @param string $sep Separator between entries
* @return bool
*/
@@ -870,6 +893,7 @@ function tpl_breadcrumbs($sep = '•') {
* @author Sean Coates <sean@caedmon.net>
* @author <fredrik@averpil.com>
* @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 <andi@splitbrain.org>
+ *
* @return bool
*/
function tpl_userinfo() {
@@ -938,6 +963,7 @@ function tpl_userinfo() {
* Print some info about the current page
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
+ *
* @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 <andi@splitbrain.org>
*/
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 <andi@splitbrain.org>
+ *
+ * @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 <andi@splitbrain.org>
*/
function tpl_getMediaFile($search, $abs = false, &$imginfo = null) {
@@ -1791,6 +1831,8 @@ function tpl_getMediaFile($search, $abs = false, &$imginfo = null) {
*
* @author Anika Henke <anika@selfthinker.org>
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file
*/
function tpl_includeFile($file) {
global $config_cascade;
@@ -1816,6 +1858,7 @@ function tpl_includeFile($file) {
* Returns <link> tag for various icon types (favicon|mobile|generic)
*
* @author Anika Henke <anika@selfthinker.org>
+ *
* @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 <anika@selfthinker.org>
+ *
+ * @return string
*/
function tpl_classes() {
global $ACT, $conf, $ID, $INFO;
diff --git a/lib/exe/xmlrpc.php b/lib/exe/xmlrpc.php
index c09daa17c00d76c8e65a4f5c515e30167f48934d..3a878ebe44349f2d50954050cbdec2c2af060379 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 2fdc697dbe46d1b1297c4fc2e61e510bd8789373..b10c544eeb05bf5007952bbd8e5c257ce06e98d5 100644
--- a/lib/plugins/acl/remote.php
+++ b/lib/plugins/acl/remote.php
@@ -1,7 +1,16 @@
<?php
+/**
+ * Class remote_plugin_acl
+ */
class remote_plugin_acl extends DokuWiki_Remote_Plugin {
- function _getMethods() {
+
+ /**
+ * Returns details about the remote plugin methods
+ *
+ * @return array
+ */
+ public function _getMethods() {
return array(
'addAcl' => 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);