more PHPDocs, unused var, small bit code reformatting

2 files changed, 146 insertions, 21 deletions

diff --git a/inc/ZipLib.class.php b/inc/ZipLib.class.php
index cec518b05..0b7bfa05e 100644
--- a/inc/ZipLib.class.php
+++ b/inc/ZipLib.class.php
@@ -16,6 +16,10 @@ class ZipLib {
     var $old_offset = 0;
     var $dirs = Array(".");
 
+    /**
+     * @param string $zip_name filename path to file
+     * @return array|int
+     */
     function get_List($zip_name) {
         $zip = @fopen($zip_name, 'rb');
         if(!$zip) return(0);
@@ -47,6 +51,11 @@ class ZipLib {
         return $ret;
     }
 
+    /**
+     * @param array $files   array filled with array(string filename, string data)
+     * @param bool  $compact
+     * @return array
+     */
     function Add($files,$compact) {
         if(!is_array($files[0])) $files=Array($files);
 
@@ -63,6 +72,10 @@ class ZipLib {
 
     /**
      * Zips recursively the $folder directory, from the $basedir directory
+     *
+     * @param string $folder filename path to file
+     * @param string|null $basedir
+     * @param string|null $parent
      */
     function Compress($folder, $basedir=null, $parent=null) {
         $full_path = $basedir."/".$parent.$folder;
@@ -73,6 +86,7 @@ class ZipLib {
         }
         $dir = new DirectoryIterator($full_path);
         foreach($dir as $file) {
+            /** @var DirectoryIterator $file */
             if(!$file->isDot()) {
                 $filename = $file->getFilename();
                 if($file->isDir()) {
@@ -87,6 +101,8 @@ class ZipLib {
 
     /**
      * Returns the Zip file
+     *
+     * @return string
      */
     function get_file() {
         $data = implode('', $this -> datasec);
@@ -97,6 +113,9 @@ class ZipLib {
             pack('V', strlen($ctrldir)) . pack('V', strlen($data)) . "\x00\x00";
     }
 
+    /**
+     * @param string $name the name of the directory
+     */
     function add_dir($name) {
         $name = str_replace("\\", "/", $name);
         $fr = "\x50\x4b\x03\x04\x0a\x00\x00\x00\x00\x00\x00\x00\x00\x00";
@@ -120,6 +139,11 @@ class ZipLib {
 
     /**
      * Add a file named $name from a string $data
+     *
+     * @param string $data
+     * @param string $name filename
+     * @param int $compact
+     * @return bool
      */
     function add_File($data, $name, $compact = 1) {
         $name     = str_replace('\\', '/', $name);
@@ -169,6 +193,9 @@ class ZipLib {
         return true;
     }
 
+    /**
+     * @return int
+     */
     function DosTime() {
         $timearray = getdate();
         if ($timearray['year'] < 1980) {
@@ -189,6 +216,11 @@ class ZipLib {
 
     /**
      * Extract a zip file $zn to the $to directory
+     *
+     * @param string $zn filename
+     * @param string $to filename path to file
+     * @param array $index
+     * @return array|int
      */
     function Extract ( $zn, $to, $index = Array(-1) ) {
         if(!@is_dir($to)) $this->_mkdir($to);
@@ -221,6 +253,11 @@ class ZipLib {
         return $stat;
     }
 
+    /**
+     * @param resource $zip
+     * @param array $header
+     * @return array
+     */
     function ReadFileHeader($zip, $header) {
         $binary_data = fread($zip, 30);
         $data = unpack('vchk/vid/vversion/vflag/vcompression/vmtime/vmdate/Vcrc/Vcompressed_size/Vsize/vfilename_len/vextra_len', $binary_data);
@@ -257,6 +294,10 @@ class ZipLib {
         return $header;
     }
 
+    /**
+     * @param resource $zip
+     * @return array
+     */
     function ReadCentralFileHeaders($zip){
         $binary_data = fread($zip, 46);
         $header = unpack('vchkid/vid/vversion/vversion_extracted/vflag/vcompression/vmtime/vmdate/Vcrc/Vcompressed_size/Vsize/vfilename_len/vextra_len/vcomment_len/vdisk/vinternal/Vexternal/Voffset', $binary_data);
@@ -298,6 +339,11 @@ class ZipLib {
         return $header;
     }
 
+    /**
+     * @param resource $zip
+     * @param string   $zip_name filename path to file
+     * @return array
+     */
     function ReadCentralDir($zip,$zip_name) {
         $size = filesize($zip_name);
         if ($size < 277){
@@ -338,6 +384,12 @@ class ZipLib {
         return $centd;
     }
 
+    /**
+     * @param array    $header
+     * @param string   $to     filename path to file
+     * @param resource $zip
+     * @return bool|int
+     */
     function ExtractFile($header,$to,$zip) {
         $header = $this->readfileheader($zip, $header);
 
@@ -418,12 +470,19 @@ class ZipLib {
      * centralize mkdir calls and use dokuwiki io functions
      *
      * @author Christopher Smith <chris@jalakai.co.uk>
+     *
+     * @param string $d filename path to file
+     * @return bool|int|string
      */
     function _mkdir($d) {
         return io_mkdir_p($d);
     }
 
-
+    /**
+     * @param string $zn
+     * @param string $name
+     * @return null|string
+     */
     function ExtractStr($zn, $name) {
         $zip = @fopen($zn,'rb');
         if(!$zip) return(null);
@@ -448,8 +507,13 @@ class ZipLib {
         return null;
     }
 
+    /**
+     * @param array $header
+     * @param resource $zip
+     * @return null|string
+     */
     function ExtractStrFile($header,$zip) {
-        $hdr = $this->readfileheader($zip);
+        $hdr = $this->readfileheader($zip, $header);
         $binary_data = '';
         if (!($header['external']==0x41FF0010) && !($header['external']==16)) {
             if ($header['compression']==0) {
@@ -487,6 +551,10 @@ class ZipLib {
         return null;
     }
 
+    /**
+     * @param string $val
+     * @return int|string
+     */
     function _ret_bytes($val) {
         $val = trim($val);
         $last = $val{strlen($val)-1};
diff --git a/inc/utf8.php b/inc/utf8.php
index c944667f7..b3f2b5fe8 100644
--- a/inc/utf8.php
+++ b/inc/utf8.php
@@ -43,6 +43,9 @@ if(!function_exists('utf8_isASCII')){
      * Checks if a string contains 7bit ASCII only
      *
      * @author Andreas Haerter <andreas.haerter@dev.mail-node.com>
+     *
+     * @param string $str
+     * @return bool
      */
     function utf8_isASCII($str){
         return (preg_match('/(?:[^\x00-\x7F])/', $str) !== 1);
@@ -56,6 +59,9 @@ if(!function_exists('utf8_strip')){
      * Returns a pure ASCII7 string
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $str
+     * @return string
      */
     function utf8_strip($str){
         $ascii = '';
@@ -75,6 +81,9 @@ if(!function_exists('utf8_check')){
      *
      * @author <bmorel@ssi.fr>
      * @link   http://www.php.net/manual/en/function.utf8-encode.php
+     *
+     * @param string $Str
+     * @return bool
      */
     function utf8_check($Str) {
         $len = strlen($Str);
@@ -105,6 +114,7 @@ if(!function_exists('utf8_basename')){
      *
      * @see basename()
      * @link   https://bugs.php.net/bug.php?id=37738
+     *
      * @param string $path     A path
      * @param string $suffix   If the name component ends in suffix this will also be cut off
      * @return string
@@ -134,6 +144,9 @@ if(!function_exists('utf8_strlen')){
      * @author <chernyshevsky at hotmail dot com>
      * @see    strlen()
      * @see    utf8_decode()
+     *
+     * @param string $string
+     * @return int
      */
     function utf8_strlen($string){
         return strlen(utf8_decode($string));
@@ -148,10 +161,11 @@ if(!function_exists('utf8_substr')){
      *
      * @author Harry Fuecks <hfuecks@gmail.com>
      * @author Chris Smith <chris@jalakai.co.uk>
+     *
      * @param string $str
      * @param int $offset number of UTF-8 characters offset (from left)
      * @param int $length (optional) length in UTF-8 characters from offset
-     * @return mixed string or false if failure
+     * @return string
      */
     function utf8_substr($str, $offset, $length = null) {
         if(UTF8_MBSTRING){
@@ -250,6 +264,14 @@ if(!function_exists('utf8_substr_replace')){
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @see    substr_replace()
+     *
+     * @param string $string      input string
+     * @param string $replacement the replacement
+     * @param int    $start       the replacing will begin at the start'th offset into string.
+     * @param int    $length      If given and is positive, it represents the length of the portion of string which is
+     *                            to be replaced. If length is zero then this function will have the effect of inserting
+     *                            replacement into string at the given start offset.
+     * @return string
      */
     function utf8_substr_replace($string, $replacement, $start , $length=0 ){
         $ret = '';
@@ -266,6 +288,7 @@ if(!function_exists('utf8_ltrim')){
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @see    ltrim()
+     *
      * @param  string $str
      * @param  string $charlist
      * @return string
@@ -286,6 +309,7 @@ if(!function_exists('utf8_rtrim')){
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @see    rtrim()
+     *
      * @param  string $str
      * @param  string $charlist
      * @return string
@@ -306,6 +330,7 @@ if(!function_exists('utf8_trim')){
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @see    trim()
+     *
      * @param  string $str
      * @param  string $charlist
      * @return string
@@ -326,6 +351,9 @@ if(!function_exists('utf8_strtolower')){
      * @author Leo Feyer <leo@typolight.org>
      * @see    strtolower()
      * @see    utf8_strtoupper()
+     *
+     * @param string $string
+     * @return string
      */
     function utf8_strtolower($string){
         if(UTF8_MBSTRING) return mb_strtolower($string,'utf-8');
@@ -344,6 +372,9 @@ if(!function_exists('utf8_strtoupper')){
      * @author Leo Feyer <leo@typolight.org>
      * @see    strtoupper()
      * @see    utf8_strtoupper()
+     *
+     * @param string $string
+     * @return string
      */
     function utf8_strtoupper($string){
         if(UTF8_MBSTRING) return mb_strtoupper($string,'utf-8');
@@ -359,7 +390,8 @@ if(!function_exists('utf8_ucfirst')){
      * Make a string's first character uppercase
      *
      * @author Harry Fuecks
-     * @param string
+     *
+     * @param string $str
      * @return string with first character as upper case (if applicable)
      */
     function utf8_ucfirst($str){
@@ -381,9 +413,10 @@ if(!function_exists('utf8_ucwords')){
      * Uppercase the first character of each word in a string
      *
      * @author Harry Fuecks
-     * @param string
-     * @return string with first char of each word uppercase
      * @see http://www.php.net/ucwords
+     *
+     * @param string $str
+     * @return string with first char of each word uppercase
      */
     function utf8_ucwords($str) {
         // Note: [\x0c\x09\x0b\x0a\x0d\x20] matches;
@@ -399,10 +432,11 @@ if(!function_exists('utf8_ucwords')){
      * You don't need to call this yourself
      *
      * @author Harry Fuecks
-     * @param  array $matches matches corresponding to a single word
-     * @return string with first char of the word in uppercase
      * @see utf8_ucwords
      * @see utf8_strtoupper
+     *
+     * @param  array $matches matches corresponding to a single word
+     * @return string with first char of the word in uppercase
      */
     function utf8_ucwords_callback($matches) {
         $leadingws = $matches[2];
@@ -420,6 +454,10 @@ if(!function_exists('utf8_deaccent')){
      * letters. Default is to deaccent both cases ($case = 0)
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $string
+     * @param int $case
+     * @return string
      */
     function utf8_deaccent($string,$case=0){
         if($case <= 0){
@@ -439,6 +477,9 @@ if(!function_exists('utf8_romanize')){
      * Romanize a non-latin string
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $string
+     * @return string
      */
     function utf8_romanize($string){
         if(utf8_isASCII($string)) return $string; //nothing to do
@@ -456,6 +497,7 @@ if(!function_exists('utf8_stripspecials')){
      * stripped chars (they are not included in $UTF8_SPECIAL_CHARS)
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
      * @param  string $string     The UTF8 string to strip of special chars
      * @param  string $repl       Replace special with this string
      * @param  string $additional Additional chars to strip (used in regexp char class)
@@ -480,9 +522,10 @@ if(!function_exists('utf8_strpos')){
      *
      * @author Leo Feyer <leo@typolight.org>
      * @see    strpos()
-     * @param  string
-     * @param  string
-     * @param  integer
+     *
+     * @param  string  $haystack
+     * @param  string  $needle
+     * @param  integer $offset
      * @return integer
      */
     function utf8_strpos($haystack, $needle, $offset=0){
@@ -512,6 +555,9 @@ if(!function_exists('utf8_tohtml')){
      * @author Tom N Harris <tnharris@whoopdedo.org>
      * @author <vpribish at shopping dot com>
      * @link   http://www.php.net/manual/en/function.utf8-decode.php
+     *
+     * @param string $str
+     * @return string
      */
     function utf8_tohtml ($str) {
         $ret = '';
@@ -542,6 +588,7 @@ if(!function_exists('utf8_unhtml')){
      * what it should be                   -> "&#38;&amp#38;"
      *
      * @author Tom N Harris <tnharris@whoopdedo.org>
+     *
      * @param  string  $str      UTF-8 encoded string
      * @param  boolean $entities Flag controlling decoding of named entities.
      * @return string  UTF-8 encoded string with numeric (and named) entities replaced.
@@ -597,10 +644,10 @@ if(!class_exists('utf8_entity_decoder')){
         }
 
         /**
-         * Wrapper aorund unicode_to_utf8()
+         * Wrapper around unicode_to_utf8()
          *
-         * @param $c string
-         * @return mixed
+         * @param string $c
+         * @return string|false
          */
         function makeutf8($c) {
             return unicode_to_utf8(array(ord($c)));
@@ -609,7 +656,7 @@ if(!class_exists('utf8_entity_decoder')){
         /**
          * Decodes any HTML entity to it's correct UTF-8 char equivalent
          *
-         * @param $ent string An entity
+         * @param string $ent An entity
          * @return string
          */
         function decode($ent) {
@@ -640,12 +687,13 @@ if(!function_exists('utf8_to_unicode')){
      *
      * @author <hsivonen@iki.fi>
      * @author Harry Fuecks <hfuecks@gmail.com>
-     * @param  string  $str UTF-8 encoded string
-     * @param  boolean $strict Check for invalid sequences?
-     * @return mixed array of unicode code points or false if UTF-8 invalid
      * @see    unicode_to_utf8
      * @link   http://hsivonen.iki.fi/php-utf8/
      * @link   http://sourceforge.net/projects/phputf8/
+     *
+     * @param  string  $str UTF-8 encoded string
+     * @param  boolean $strict Check for invalid sequences?
+     * @return mixed array of unicode code points or false if UTF-8 invalid
      */
     function utf8_to_unicode($str,$strict=false) {
         $mState = 0;     // cached expected number of octets after the current octet
@@ -815,7 +863,8 @@ if(!function_exists('unicode_to_utf8')){
      *
      * @param  array $arr of unicode code points representing a string
      * @param  boolean $strict Check for invalid sequences?
-     * @return mixed UTF-8 string or false if array contains invalid code points
+     * @return string|false UTF-8 string or false if array contains invalid code points
+     *
      * @author <hsivonen@iki.fi>
      * @author Harry Fuecks <hfuecks@gmail.com>
      * @see    utf8_to_unicode
@@ -896,6 +945,10 @@ if(!function_exists('utf8_to_utf16be')){
      * UTF-8 to UTF-16BE conversion.
      *
      * Maybe really UCS-2 without mb_string due to utf8_to_unicode limits
+     *
+     * @param string $str
+     * @param bool $bom
+     * @return string
      */
     function utf8_to_utf16be(&$str, $bom = false) {
         $out = $bom ? "\xFE\xFF" : '';
@@ -914,6 +967,9 @@ if(!function_exists('utf16be_to_utf8')){
      * UTF-8 to UTF-16BE conversion.
      *
      * Maybe really UCS-2 without mb_string due to utf8_to_unicode limits
+     *
+     * @param string $str
+     * @return false|string
      */
     function utf16be_to_utf8(&$str) {
         $uni = unpack('n*',$str);
@@ -933,6 +989,7 @@ if(!function_exists('utf8_bad_replace')){
      *
      * @author Harry Fuecks <hfuecks@gmail.com>
      * @see http://www.w3.org/International/questions/qa-forms-utf-8
+     *
      * @param string $str to search
      * @param string $replace to replace bad bytes with (defaults to '?') - use ASCII
      * @return string
@@ -967,8 +1024,8 @@ if(!function_exists('utf8_correctIdx')){
     /**
      * adjust a byte index into a utf8 string to a utf8 character boundary
      *
-     * @param $str   string   utf8 character string
-     * @param $i     int      byte index into $str
+     * @param string $str   utf8 character string
+     * @param int    $i     byte index into $str
      * @param $next  bool     direction to search for boundary,
      *                           false = up (current character)
      *                           true = down (next character)