From 84657ea239c6b7c08f5e4ffb58170d6521cdbb44 Mon Sep 17 00:00:00 2001
From: Gerrit Uitslag <klapinklapin@gmail.com>
Date: Wed, 21 May 2014 11:17:19 +0200
Subject: [PATCH] PHPdocs pageutils
---
inc/pageutils.php | 67 +++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 65 insertions(+), 2 deletions(-)
diff --git a/inc/pageutils.php b/inc/pageutils.php
index b678aa7c3..79b703ddc 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 */
@@ -179,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));
@@ -188,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;
@@ -208,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) {
@@ -238,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));
@@ -296,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;
@@ -307,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;
@@ -320,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;
@@ -334,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, '');
@@ -349,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;
@@ -371,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'){
@@ -396,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;
@@ -441,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);
@@ -452,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;
@@ -543,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(
@@ -556,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;
@@ -575,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);
@@ -587,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 '*';
@@ -611,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;
@@ -636,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;
--
GitLab