diff --git a/inc/changelog.php b/inc/changelog.php
index f0788d8961e9a00f20c5b5e9fc9dd7f8c7bb3f45..8c14f21b06ae980d3eea0967efcfb825e84892b0 100644
--- a/inc/changelog.php
+++ b/inc/changelog.php
@@ -18,6 +18,9 @@ define('DOKU_CHANGE_TYPE_REVERT', 'R');
* parses a changelog line into it's components
*
* @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @param string $line changelog line
+ * @return array|bool parsed line or false
*/
function parseChangelogLine($line) {
$tmp = explode("\t", $line);
@@ -43,7 +46,7 @@ function parseChangelogLine($line) {
* @param String $summary Summary of the change
* @param mixed $extra In case of a revert the revision (timestmp) of the reverted page
* @param array $flags Additional flags in a key value array.
- * Availible flags:
+ * Available flags:
* - ExternalEdit - mark as an external edit.
*
* @author Andreas Gohr <andi@splitbrain.org>
@@ -116,6 +119,15 @@ function addLogEntry($date, $id, $type=DOKU_CHANGE_TYPE_EDIT, $summary='', $extr
* @author Andreas Gohr <andi@splitbrain.org>
* @author Esther Brunner <wikidesign@gmail.com>
* @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @param int $date Timestamp of the change
+ * @param String $id Name of the affected page
+ * @param String $type Type of the change see DOKU_CHANGE_TYPE_*
+ * @param String $summary Summary of the change
+ * @param mixed $extra In case of a revert the revision (timestmp) of the reverted page
+ * @param array $flags Additional flags in a key value array.
+ * Available flags:
+ * - (none, so far)
*/
function addMediaLogEntry($date, $id, $type=DOKU_CHANGE_TYPE_EDIT, $summary='', $extra='', $flags=null){
global $conf;
@@ -294,6 +306,12 @@ function getRecentsSince($from,$to=null,$ns='',$flags=0){
* @see getRecents()
* @author Andreas Gohr <andi@splitbrain.org>
* @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @param string $line changelog line
+ * @param string $ns restrict to given namespace
+ * @param int $flags flags to control which changes are included
+ * @param array $seen listing of seen pages
+ * @return array|bool false or array with info about a change
*/
function _handleRecent($line,$ns,$flags,&$seen){
if(empty($line)) return false; //skip empty lines
@@ -778,9 +796,9 @@ abstract class ChangeLog {
* Read chunk and return array with lines of given chunck.
* Has no check if $head and $tail are really at a new line
*
- * @param $fp resource filepointer
- * @param $head int start point chunck
- * @param $tail int end point chunck
+ * @param resource $fp resource filepointer
+ * @param int $head start point chunck
+ * @param int $tail end point chunck
* @return array lines read from chunck
*/
protected function readChunk($fp, $head, $tail) {
@@ -804,8 +822,8 @@ abstract class ChangeLog {
/**
* Set pointer to first new line after $finger and return its position
*
- * @param resource $fp filepointer
- * @param $finger int a pointer
+ * @param resource $fp filepointer
+ * @param int $finger a pointer
* @return int pointer
*/
protected function getNewlinepointer($fp, $finger) {
@@ -886,7 +904,7 @@ abstract class ChangeLog {
*/
protected function retrieveRevisionsAround($rev, $max) {
//get lines from changelog
- list($fp, $lines, $starthead, $starttail, $eof) = $this->readloglines($rev);
+ list($fp, $lines, $starthead, $starttail, /* $eof */) = $this->readloglines($rev);
if(empty($lines)) return false;
//parse chunk containing $rev, and read forward more chunks until $max/2 is reached
@@ -1010,7 +1028,7 @@ class MediaChangelog extends ChangeLog {
* @author Kate Arzamastseva <pshns@ukr.net>
*/
function getRevisionInfo($id, $rev, $chunk_size = 8192, $media = false) {
- dbg_deprecated('class PageChangeLog or class MediaChanglog');
+ dbg_deprecated('class PageChangeLog or class MediaChangelog');
if($media) {
$changelog = new MediaChangeLog($id, $chunk_size);
} else {
@@ -1025,10 +1043,6 @@ function getRevisionInfo($id, $rev, $chunk_size = 8192, $media = false) {
* only that a line with the date exists in the changelog.
* By default the current revision is skipped.
*
- * id: the page of interest
- * first: skip the first n changelog lines
- * num: number of revisions to return
- *
* The current revision is automatically skipped when the page exists.
* See $INFO['meta']['last_change'] for the current revision.
*
@@ -1041,9 +1055,16 @@ function getRevisionInfo($id, $rev, $chunk_size = 8192, $media = false) {
*
* @author Ben Coburn <btcoburn@silicodon.net>
* @author Kate Arzamastseva <pshns@ukr.net>
+ *
+ * @param string $id the page of interest
+ * @param int $first skip the first n changelog lines
+ * @param int $num number of revisions to return
+ * @param int $chunk_size
+ * @param bool $media
+ * @return array
*/
function getRevisions($id, $first, $num, $chunk_size = 8192, $media = false) {
- dbg_deprecated('class PageChangeLog or class MediaChanglog');
+ dbg_deprecated('class PageChangeLog or class MediaChangelog');
if($media) {
$changelog = new MediaChangeLog($id, $chunk_size);
} else {
diff --git a/inc/common.php b/inc/common.php
index ecd743a96eb650af29985b40bea54f2ea7ee3be6..0fe33c5b1f97005e38ae6b83c948e28b9f5507f0 100644
--- a/inc/common.php
+++ b/inc/common.php
@@ -22,6 +22,9 @@ define('RECENTS_MEDIA_PAGES_MIXED', 32);
*
* @author Andreas Gohr <andi@splitbrain.org>
* @see htmlspecialchars()
+ *
+ * @param string $string the string being converted
+ * @return string converted string
*/
function hsc($string) {
return htmlspecialchars($string, ENT_QUOTES, 'UTF-8');
@@ -33,6 +36,9 @@ function hsc($string) {
* You can give an indention as optional parameter
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $string line of text
+ * @param int $indent number of spaces indention
*/
function ptln($string, $indent = 0) {
echo str_repeat(' ', $indent)."$string\n";
@@ -42,6 +48,9 @@ function ptln($string, $indent = 0) {
* strips control characters (<32) from the given string
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param $string string being stripped
+ * @return string
*/
function stripctl($string) {
return preg_replace('/[\x00-\x1F]+/s', '', $string);
@@ -63,6 +72,9 @@ function getSecurityToken() {
/**
* Check the secret CSRF token
+ *
+ * @param null|string $token security token or null to read it from request variable
+ * @return bool success if the token matched
*/
function checkSecurityToken($token = null) {
/** @var Input $INPUT */
@@ -81,6 +93,9 @@ function checkSecurityToken($token = null) {
* Print a hidden form field with a secret CSRF token
*
* @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
*/
function formSecurityToken($print = true) {
$ret = '<div class="no"><input type="hidden" name="sectok" value="'.getSecurityToken().'" /></div>'."\n";
@@ -93,6 +108,11 @@ function formSecurityToken($print = true) {
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Chris Smith <chris@jalakai.co.uk>
+ *
+ * @param string $id pageid
+ * @param bool $htmlClient add info about whether is mobile browser
+ * @return array with info for a request of $id
+ *
*/
function basicinfo($id, $htmlClient=true){
global $USERINFO;
@@ -139,6 +159,8 @@ function basicinfo($id, $htmlClient=true){
* array.
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return array with info about current document
*/
function pageinfo() {
global $ID;
@@ -246,6 +268,8 @@ function pageinfo() {
/**
* Return information about the current media item as an associative array.
+ *
+ * @return array with info about current media item
*/
function mediainfo(){
global $NS;
@@ -261,6 +285,10 @@ function mediainfo(){
* Build an string of URL parameters
*
* @author Andreas Gohr
+ *
+ * @param array $params array with key-value pairs
+ * @param string $sep series of pairs are separated by this character
+ * @return string query string
*/
function buildURLparams($params, $sep = '&') {
$url = '';
@@ -281,6 +309,10 @@ function buildURLparams($params, $sep = '&') {
* Skips keys starting with '_', values get HTML encoded
*
* @author Andreas Gohr
+ *
+ * @param array $params array with (attribute name-attribute value) pairs
+ * @param bool $skipempty skip empty string values?
+ * @return string
*/
function buildAttributes($params, $skipempty = false) {
$url = '';
@@ -302,6 +334,8 @@ function buildAttributes($params, $skipempty = false) {
* This builds the breadcrumb trail and returns it as array
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return array(pageid=>name, ... )
*/
function breadcrumbs() {
// we prepare the breadcrumbs early for quick session closing
@@ -361,6 +395,10 @@ function breadcrumbs() {
* Urlencoding is ommitted when the second parameter is false
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id pageid being filtered
+ * @param bool $ue apply urlencoding?
+ * @return string
*/
function idfilter($id, $ue = true) {
global $conf;
@@ -574,6 +612,8 @@ function ml($id = '', $more = '', $direct = true, $sep = '&', $abs = false)
* Consider using wl() instead, unless you absoutely need the doku.php endpoint
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return string
*/
function script() {
return DOKU_BASE.DOKU_SCRIPT;
@@ -600,6 +640,7 @@ function script() {
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Michael Klier <chi@chimeric.de>
+ *
* @param string $text - optional text to check, if not given the globals are used
* @return bool - true if a spam word was found
*/
@@ -668,6 +709,7 @@ function checkwordblock($text = '') {
* headers
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
* @param boolean $single If set only a single IP is returned
* @return string
*/
@@ -739,6 +781,8 @@ function clientIP($single = false) {
* Adapted from the example code at url below
*
* @link http://www.brainhandles.com/2007/10/15/detecting-mobile-browsers/#code
+ *
+ * @return bool if true, client is mobile browser; otherwise false
*/
function clientismobile() {
/* @var Input $INPUT */
@@ -763,6 +807,7 @@ function clientismobile() {
* If $conf['dnslookups'] is disabled it simply returns the input string
*
* @author Glen Harris <astfgl@iamnota.org>
+ *
* @param string $ips comma separated list of IP addresses
* @return string a comma separated list of hostnames
*/
@@ -789,6 +834,9 @@ function gethostsbyaddrs($ips) {
* removes stale lockfiles
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id page id
+ * @return bool page is locked?
*/
function checklock($id) {
global $conf;
@@ -819,6 +867,8 @@ function checklock($id) {
* Lock a page for editing
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id page id to lock
*/
function lock($id) {
global $conf;
@@ -841,6 +891,7 @@ function lock($id) {
* Unlock a page if it was locked by the user
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
* @param string $id page id to unlock
* @return bool true if a lock was removed
*/
@@ -866,6 +917,9 @@ function unlock($id) {
*
* @see formText() for 2crlf conversion
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $text
+ * @return string
*/
function cleanText($text) {
$text = preg_replace("/(\015\012)|(\015)/", "\012", $text);
@@ -885,6 +939,9 @@ function cleanText($text) {
*
* @see cleanText() for 2unix conversion
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $text
+ * @return string
*/
function formText($text) {
$text = str_replace("\012", "\015\012", $text);
@@ -895,6 +952,10 @@ function formText($text) {
* Returns the specified local text in raw format
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id page id
+ * @param string $ext extension of file being read, default 'txt'
+ * @return string
*/
function rawLocale($id, $ext = 'txt') {
return io_readFile(localeFN($id, $ext));
@@ -904,6 +965,10 @@ function rawLocale($id, $ext = 'txt') {
* Returns the raw WikiText
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id page id
+ * @param string $rev timestamp when a revision of wikitext is desired
+ * @return string
*/
function rawWiki($id, $rev = '') {
return io_readWikiPage(wikiFN($id, $rev), $id, $rev);
@@ -914,6 +979,9 @@ function rawWiki($id, $rev = '') {
*
* @triggers COMMON_PAGETPL_LOAD
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id the id of the page to be created
+ * @return string parsed pagetemplate content
*/
function pageTemplate($id) {
global $conf;
@@ -965,6 +1033,9 @@ function pageTemplate($id) {
* This works on data from COMMON_PAGETPL_LOAD
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $data array with event data
+ * @return string
*/
function parsePageTemplate(&$data) {
/**
@@ -1032,6 +1103,11 @@ function parsePageTemplate(&$data) {
* The returned order is prefix, section and suffix.
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $range in form "from-to"
+ * @param string $id page id
+ * @param string $rev optional, the revision timestamp
+ * @return array with three slices
*/
function rawWikiSlices($range, $id, $rev = '') {
$text = io_readWikiPage(wikiFN($id, $rev), $id, $rev);
@@ -1056,6 +1132,12 @@ function rawWikiSlices($range, $id, $rev = '') {
* lines between sections if needed (used on saving).
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $pre prefix
+ * @param string $text text in the middle
+ * @param string $suf suffix
+ * @param bool $pretty add additional empty lines between sections
+ * @return string
*/
function con($pre, $text, $suf, $pretty = false) {
if($pretty) {
@@ -1080,6 +1162,11 @@ function con($pre, $text, $suf, $pretty = false) {
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @param string $id page id
+ * @param string $text wikitext being saved
+ * @param string $summary summary of text update
+ * @param bool $minor mark this saved version as minor update
*/
function saveWikiText($id, $text, $summary, $minor = false) {
/* Note to developers:
@@ -1184,6 +1271,9 @@ function saveWikiText($id, $text, $summary, $minor = false) {
* revision date
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id page id
+ * @return int|string revision timestamp
*/
function saveOldRevision($id) {
$oldf = wikiFN($id);
@@ -1203,8 +1293,8 @@ function saveOldRevision($id) {
* @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
- *
* @return bool
+ *
* @author Andreas Gohr <andi@splitbrain.org>
*/
function notify($id, $who, $rev = '', $summary = '', $minor = false, $replace = array()) {
@@ -1220,7 +1310,7 @@ function notify($id, $who, $rev = '', $summary = '', $minor = false, $replace =
} elseif($who == 'subscribers') {
if(!actionOK('subscribe')) return false; //subscribers enabled?
if($conf['useacl'] && $INPUT->server->str('REMOTE_USER') && $minor) return false; //skip minors
- $data = array('id' => $id, 'addresslist' => '', 'self' => false);
+ $data = array('id' => $id, 'addresslist' => '', 'self' => false, 'replacements' => $replace);
trigger_event(
'COMMON_NOTIFY_ADDRESSLIST', $data,
array(new Subscription(), 'notifyaddresses')
@@ -1242,6 +1332,8 @@ function notify($id, $who, $rev = '', $summary = '', $minor = false, $replace =
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Todd Augsburger <todd@rollerorgans.com>
+ *
+ * @return array|string
*/
function getGoogleQuery() {
/* @var Input $INPUT */
@@ -1283,6 +1375,7 @@ function getGoogleQuery() {
* @param int $size A file size
* @param int $dec A number of decimal places
* @return string human readable size
+ *
* @author Martin Benjamin <b.martin@cybernet.ch>
* @author Aidan Lister <aidan@php.net>
* @version 1.0.0
@@ -1304,6 +1397,9 @@ function filesize_h($size, $dec = 1) {
* Return the given timestamp as human readable, fuzzy age
*
* @author Andreas Gohr <gohr@cosmocode.de>
+ *
+ * @param int $dt timestamp
+ * @return string
*/
function datetime_h($dt) {
global $lang;
@@ -1338,6 +1434,10 @@ function datetime_h($dt) {
*
* @see datetime_h
* @author Andreas Gohr <gohr@cosmocode.de>
+ *
+ * @param int|null $dt timestamp when given, null will take current timestamp
+ * @param string $format empty default to $conf['dformat'], or provide format as recognized by strftime()
+ * @return string
*/
function dformat($dt = null, $format = '') {
global $conf;
@@ -1355,6 +1455,7 @@ function dformat($dt = null, $format = '') {
*
* @author <ungu at terong dot com>
* @link http://www.php.net/manual/en/function.date.php#54072
+ *
* @param int $int_date: current date in UNIX timestamp
* @return string
*/
@@ -1371,6 +1472,9 @@ function date_iso8601($int_date) {
*
* @author Harry Fuecks <hfuecks@gmail.com>
* @author Christopher Smith <chris@jalakai.co.uk>
+ *
+ * @param string $email email address
+ * @return string
*/
function obfuscate($email) {
global $conf;
@@ -1398,6 +1502,10 @@ function obfuscate($email) {
* Removes quoting backslashes
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $string
+ * @param string $char backslashed character
+ * @return string
*/
function unslash($string, $char = "'") {
return str_replace('\\'.$char, $char, $string);
@@ -1408,6 +1516,9 @@ function unslash($string, $char = "'") {
*
* @author <gilthans dot NO dot SPAM at gmail dot com>
* @link http://de3.php.net/manual/en/ini.core.php#79564
+ *
+ * @param string $v shorthands
+ * @return int|string
*/
function php_to_byte($v) {
$l = substr($v, -1);
@@ -1425,6 +1536,7 @@ function php_to_byte($v) {
/** @noinspection PhpMissingBreakStatementInspection */
case 'M':
$ret *= 1024;
+ /** @noinspection PhpMissingBreakStatementInspection */
case 'K':
$ret *= 1024;
break;
@@ -1437,6 +1549,9 @@ function php_to_byte($v) {
/**
* Wrapper around preg_quote adding the default delimiter
+ *
+ * @param string $string
+ * @return string
*/
function preg_quote_cb($string) {
return preg_quote($string, '/');
@@ -1470,7 +1585,7 @@ function shorten($keep, $short, $max, $min = 9, $char = '…') {
* Return the users realname or e-mail address for use
* in page footer and recent changes pages
*
- * @param string|bool $username or false when currently logged-in user should be used
+ * @param string|null $username or null when currently logged-in user should be used
* @param bool $textonly true returns only plain text, true allows returning html
* @return string html or plain text(not escaped) of formatted user name
*
@@ -1483,7 +1598,7 @@ function editorinfo($username, $textonly = false) {
/**
* Returns users realname w/o link
*
- * @param string|bool $username or false when currently logged-in user should be used
+ * @param string|null $username or null when currently logged-in user should be used
* @param bool $textonly true returns only plain text, true allows returning html
* @return string html or plain text(not escaped) of formatted user name
*
@@ -1606,6 +1721,7 @@ function userlink($username = null, $textonly = false) {
* When no image exists, returns an empty string
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
* @param string $type - type of image 'badge' or 'button'
* @return string
*/
@@ -1614,7 +1730,6 @@ function license_img($type) {
global $conf;
if(!$conf['license']) return '';
if(!is_array($license[$conf['license']])) return '';
- $lic = $license[$conf['license']];
$try = array();
$try[] = 'lib/images/license/'.$type.'/'.$conf['license'].'.png';
$try[] = 'lib/images/license/'.$type.'/'.$conf['license'].'.gif';
@@ -1636,9 +1751,8 @@ function license_img($type) {
* @author Filip Oscadal <webmaster@illusionsoftworks.cz>
* @author Andreas Gohr <andi@splitbrain.org>
*
- * @param int $mem Size of memory you want to allocate in bytes
- * @param int $bytes
- * @internal param int $used already allocated memory (see above)
+ * @param int $mem Size of memory you want to allocate in bytes
+ * @param int $bytes already allocated memory (see above)
* @return bool
*/
function is_mem_available($mem, $bytes = 1048576) {
@@ -1669,6 +1783,8 @@ function is_mem_available($mem, $bytes = 1048576) {
*
* @link http://support.microsoft.com/kb/q176113/
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $url url being directed to
*/
function send_redirect($url) {
/* @var Input $INPUT */
@@ -1740,6 +1856,10 @@ function valid_input_set($param, $valid_values, $array, $exc = '') {
/**
* Read a preference from the DokuWiki cookie
* (remembering both keys & values are urlencoded)
+ *
+ * @param string $pref preference key
+ * @param mixed $default value returned when preference not found
+ * @return string preference value
*/
function get_doku_pref($pref, $default) {
$enc_pref = urlencode($pref);
@@ -1758,6 +1878,9 @@ function get_doku_pref($pref, $default) {
/**
* Add a preference to the DokuWiki cookie
* (remembering $_COOKIE['DOKU_PREFS'] is urlencoded)
+ *
+ * @param string $pref preference key
+ * @param string $val preference value
*/
function set_doku_pref($pref, $val) {
global $conf;
diff --git a/inc/pageutils.php b/inc/pageutils.php
index 8474c5697113751e7cbbd92ae758eeb97c8e79e1..5f62926e42778307e095d1a1aa91923f166ce858 100644
--- a/inc/pageutils.php
+++ b/inc/pageutils.php
@@ -17,6 +17,10 @@
* If the second parameter is true (default) the ID is cleaned.
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $param the $_REQUEST variable name, default 'id'
+ * @param bool $clean if true, ID is cleaned
+ * @return mixed|string
*/
function getID($param='id',$clean=true){
/** @var Input $INPUT */
@@ -146,6 +150,9 @@ function cleanID($raw_id,$ascii=false){
* Return namespacepart of a wiki ID
*
* @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)
*/
function getNS($id){
$pos = strrpos((string)$id,':');
@@ -159,6 +166,9 @@ function getNS($id){
* Returns the ID without the namespace
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id
+ * @return string
*/
function noNS($id) {
$pos = strrpos($id, ':');
@@ -173,6 +183,9 @@ function noNS($id) {
* Returns the current namespace
*
* @author Nathan Fritz <fritzn@crown.edu>
+ *
+ * @param string $id
+ * @return string
*/
function curNS($id) {
return noNS(getNS($id));
@@ -182,6 +195,9 @@ function curNS($id) {
* Returns the ID without the namespace or current namespace for 'start' pages
*
* @author Nathan Fritz <fritzn@crown.edu>
+ *
+ * @param string $id
+ * @return string
*/
function noNSorNS($id) {
global $conf;
@@ -202,6 +218,7 @@ function noNSorNS($id) {
* @param string $title The headline title
* @param array|bool $check Existing IDs (title => number)
* @return string the title
+ *
* @author Andreas Gohr <andi@splitbrain.org>
*/
function sectionID($title,&$check) {
@@ -232,6 +249,11 @@ function sectionID($title,&$check) {
* parameters as for wikiFN
*
* @author Chris Smith <chris@jalakai.co.uk>
+ *
+ * @param string $id page id
+ * @param string|int $rev empty or revision timestamp
+ * @param bool $clean flag indicating that $id should be cleaned (see wikiFN as well)
+ * @return bool exists?
*/
function page_exists($id,$rev='',$clean=true) {
return @file_exists(wikiFN($id,$rev,$clean));
@@ -290,6 +312,9 @@ function wikiFN($raw_id,$rev='',$clean=true){
* Returns the full path to the file for locking the page while editing.
*
* @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @param string $id page id
+ * @return string full path
*/
function wikiLockFN($id) {
global $conf;
@@ -301,6 +326,10 @@ function wikiLockFN($id) {
* returns the full path to the meta file specified by ID and extension
*
* @author Steven Danz <steven-danz@kc.rr.com>
+ *
+ * @param string $id page id
+ * @param string $ext file extension
+ * @return string full path
*/
function metaFN($id,$ext){
global $conf;
@@ -314,6 +343,10 @@ function metaFN($id,$ext){
* returns the full path to the media's meta file specified by ID and extension
*
* @author Kate Arzamastseva <pshns@ukr.net>
+ *
+ * @param string $id media id
+ * @param string $ext extension of media
+ * @return string
*/
function mediaMetaFN($id,$ext){
global $conf;
@@ -328,6 +361,9 @@ function mediaMetaFN($id,$ext){
*
* @author Esther Brunner <esther@kaffeehaus.ch>
* @author Michael Hamann <michael@content-space.de>
+ *
+ * @param string $id page id
+ * @return array
*/
function metaFiles($id){
$basename = metaFN($id, '');
@@ -343,6 +379,10 @@ function metaFiles($id){
*
* @author Andreas Gohr <andi@splitbrain.org>
* @author Kate Arzamastseva <pshns@ukr.net>
+ *
+ * @param string $id media id
+ * @param string|int $rev empty string or revision timestamp
+ * @return string full path
*/
function mediaFN($id, $rev=''){
global $conf;
@@ -365,6 +405,7 @@ function mediaFN($id, $rev=''){
* @param string $id The id of the local file
* @param string $ext The file extension (usually txt)
* @return string full filepath to localized file
+ *
* @author Andreas Gohr <andi@splitbrain.org>
*/
function localeFN($id,$ext='txt'){
@@ -390,6 +431,11 @@ function localeFN($id,$ext='txt'){
* http://www.php.net/manual/en/function.realpath.php#57016
*
* @author <bart at mediawave dot nl>
+ *
+ * @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
*/
function resolve_id($ns,$id,$clean=true){
global $conf;
@@ -435,6 +481,10 @@ function resolve_id($ns,$id,$clean=true){
* Returns a full media id
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $ns namespace which is context of id
+ * @param string &$page (reference) relative media id, updated to resolved id
+ * @param bool &$exists (reference) updated with existance of media
*/
function resolve_mediaid($ns,&$page,&$exists){
$page = resolve_id($ns,$page);
@@ -446,6 +496,10 @@ function resolve_mediaid($ns,&$page,&$exists){
* Returns a full page id
*
* @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $ns namespace which is context of id
+ * @param string &$page (reference) relative page id, updated to resolved id
+ * @param bool &$exists (reference) updated with existance of media
*/
function resolve_pageid($ns,&$page,&$exists){
global $conf;
@@ -537,6 +591,9 @@ function getCacheName($data,$ext=''){
* Checks a pageid against $conf['hidepages']
*
* @author Andreas Gohr <gohr@cosmocode.de>
+ *
+ * @param string $id page id
+ * @return bool
*/
function isHiddenPage($id){
$data = array(
@@ -550,7 +607,7 @@ function isHiddenPage($id){
/**
* callback checks if page is hidden
*
- * @param array $data event data see isHiddenPage()
+ * @param array $data event data - see isHiddenPage()
*/
function _isHiddenPage(&$data) {
global $conf;
@@ -569,6 +626,9 @@ function _isHiddenPage(&$data) {
* Reverse of isHiddenPage
*
* @author Andreas Gohr <gohr@cosmocode.de>
+ *
+ * @param string $id page id
+ * @return bool
*/
function isVisiblePage($id){
return !isHiddenPage($id);
@@ -581,8 +641,10 @@ function isVisiblePage($id){
* “*â€. Output is escaped.
*
* @author Adrian Lang <lang@cosmocode.de>
+ *
+ * @param string $id page id
+ * @return string
*/
-
function prettyprint_id($id) {
if (!$id || $id === ':') {
return '*';
@@ -605,6 +667,10 @@ function prettyprint_id($id) {
*
* @author Andreas Gohr <andi@splitbrain.org>
* @see urlencode
+ *
+ * @param string $file file name
+ * @param bool $safe if true, only encoded when non ASCII characters detected
+ * @return string
*/
function utf8_encodeFN($file,$safe=true){
global $conf;
@@ -630,6 +696,9 @@ function utf8_encodeFN($file,$safe=true){
*
* @author Andreas Gohr <andi@splitbrain.org>
* @see urldecode
+ *
+ * @param string $file file name
+ * @return string
*/
function utf8_decodeFN($file){
global $conf;
diff --git a/inc/subscription.php b/inc/subscription.php
index a6f3dec44acda1bc463d18b8685b2756d314ddfb..aab6de926464448cfc687927646815cc09fd9764 100644
--- a/inc/subscription.php
+++ b/inc/subscription.php
@@ -650,9 +650,11 @@ class Subscription {
* @todo move the whole functionality into this class, trigger SUBSCRIPTION_NOTIFY_ADDRESSLIST instead,
* use an array for the addresses within it
*
- * @param array &$data Containing $id (the page id), $self (whether the author
- * should be notified, $addresslist (current email address
- * list)
+ * @param array &$data Containing the entries:
+ * - $id (the page id),
+ * - $self (whether the author should be notified,
+ * - $addresslist (current email address list)
+ * - $replacements (array of additional string substitutions, @KEY@ to be replaced by value)
*/
public function notifyaddresses(&$data) {
if(!$this->isenabled()) return;