Many PHPDocs, some unused and dyn declared vars

many PHPDocs
some unused variables
some dynamically declared variables declared

1 files changed, 69 insertions, 2 deletions

diff --git a/inc/io.php b/inc/io.php
index 27a34b045..bfa394a17 100644
--- a/inc/io.php
+++ b/inc/io.php
@@ -20,6 +20,7 @@ if(!defined('DOKU_INC')) die('meh.');
  * @param string $id      - a pageid, the namespace of that id will be tried to deleted
  * @param string $basedir - the config name of the type to delete (datadir or mediadir usally)
  * @return bool - true if at least one namespace was deleted
+ *
  * @author  Andreas Gohr <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(