Merge remote-tracking branch master into revisions

1 files changed, 71 insertions, 2 deletions

diff --git a/inc/pageutils.php b/inc/pageutils.php
index d5d33e76f..9ea75c8aa 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, $data_at=false) {
     if($rev !== '' && $date_at) {
@@ -296,6 +318,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;
@@ -307,6 +332,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;
@@ -320,6 +349,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;
@@ -334,6 +367,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, '');
@@ -349,6 +385,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;
@@ -371,6 +411,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'){
@@ -396,6 +437,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;
@@ -441,6 +487,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,$rev='',$date_at=false){
     if($rev !== '' &&  $date_at){
@@ -459,6 +509,10 @@ function resolve_mediaid($ns,&$page,&$exists,$rev='',$date_at=false){
  * 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,$rev='',$date_at=false ){
     global $conf;
@@ -556,6 +610,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(
@@ -569,7 +626,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;
@@ -588,6 +645,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);
@@ -600,8 +660,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 '*';
@@ -624,6 +686,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;
@@ -649,6 +715,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;