phpdoc cleanup

plugins/newmail/config-sample.php

@@ -5,7 +5,7 @@
  * Sample configuration file
  * @version $Id$
  * @package plugins
- * @subpackage new_mail
+ * @subpackage newmail
  */
 
 // Set $allowsound to false if you don't want sound files available

plugins/newmail/config_default.php

@@ -5,18 +5,34 @@
  * Default configuration file
  * @version $Id$
  * @package plugins
- * @subpackage new_mail
+ * @subpackage newmail
  */
 
-// Set $allowsound to false if you don't want sound files available
+/**
+ * Set $allowsound to false if you don't want sound files available
+ * @global boolean $newmail_allowsound
+ */
 global $newmail_allowsound;
 $newmail_allowsound = true;
 
-// controls insertion of embed tags
+/**
+ * controls insertion of embed tags
+ * @global boolean $newmail_mediacompat_mode
+ */
 global $newmail_mediacompat_mode;
 $newmail_mediacompat_mode=false;
 
-// Default setting should create empty array.
-global $newmail_mmedia;
+/**
+ * List of available multimedia files.
+ *
+ * For example.
+ * $newmail_mmedia['notify']['types'] = array(SM_NEWMAIL_FILETYPE_SWF,SM_NEWMAIL_FILETYPE_MP3,SM_NEWMAIL_FILETYPE_WAV);
+ * $newmail_mmedia['notify']['args']  = array('width'=>0,'height'=>0);
+ *
+ * These two entries say that media/ directory contains notify.swf, notify.mp3 and notify.wav files
+ * Object entities for these files should be use zero width and height attributes
+ * @global array $newmail_mmedia
+ */
+ global $newmail_mmedia;
 $newmail_mmedia=array();
 ?>

plugins/newmail/functions.php

@@ -5,7 +5,7 @@
  * Functions
  * @version $Id$
  * @package plugins
- * @subpackage new_mail
+ * @subpackage newmail
  */
 
 /** file type defines */
@@ -66,9 +66,10 @@ function newmail_detect_filetype($contents,$type) {
 }
 
 /**
+ * Function tries to detect uploaded file type
  * @param string $type
  * @param string $filename
- * @return integer
+ * @return integer One of SM_NEWMAIL_FILETYPE_* defines or false.
  */
 function newmail_get_mediatype($type,$filename) {
     switch ($type) {
@@ -100,9 +101,9 @@ function newmail_get_mediatype($type,$filename) {
 /**
  * Function provides filetype detection for browsers, that
  * upload files with application/octet-stream file type.
- * Ex. Opera.
+ * Ex. some version of Opera.
  * @param string $filename
- * @return string
+ * @return integer One of SM_NEWMAIL_FILETYPE_* defines or false.
  */
 function newmail_get_mediatype_by_ext($filename) {
     if (preg_match("/\.wav$/i",$filename)) return SM_NEWMAIL_FILETYPE_WAV;
@@ -164,6 +165,7 @@ function newmail_media_objects($object,$types,$path,$args=array(),$extra='',$add
  * Warnings:
  * * Returned string does not contain html closing tag.
  * * This is internal function, use newmail_media_objects() instead
+ * @link http://www.w3.org/TR/html4/struct/objects.html#edef-OBJECT W3.org specs
  * @param string $object object name
  * @param integer $type media object type
  * @param string $path URL to media object

plugins/newmail/loadfile.php

@@ -5,7 +5,7 @@
  * Script loads user's media file.
  * @version $Id$
  * @package plugins
- * @subpackage new_mail
+ * @subpackage newmail
  */
 
 /**
@@ -23,60 +23,60 @@ sqgetGlobalVar('username',$username,SQ_SESSION);
 global $data_dir;
 
 $media = getPref($data_dir,$username,'newmail_media', '(none)');
-    // get other prefs
-    $newmail_userfile_type=getPref($data_dir,$username,'newmail_userfile_type',false);
+// get other prefs
+$newmail_userfile_type=getPref($data_dir,$username,'newmail_userfile_type',false);
     
-    $newmail_userfile_location=getHashedFile($username, $data_dir, $username . '.sound');
+$newmail_userfile_location=getHashedFile($username, $data_dir, $username . '.sound');
 
-    if ($newmail_userfile_type!=false && file_exists($newmail_userfile_location)) {
-        // open media file
-        $newmail_userfile_handle = fopen($newmail_userfile_location,'rb');
-        if ($newmail_userfile_handle) {
-            $newmail_userfile_filesize = filesize($newmail_userfile_location);
-            $newmail_userfile_contents = fread($newmail_userfile_handle,$newmail_userfile_filesize);
-            fclose ($newmail_userfile_handle);
+if ($newmail_userfile_type!=false && file_exists($newmail_userfile_location)) {
+    // open media file
+    $newmail_userfile_handle = fopen($newmail_userfile_location,'rb');
+    if ($newmail_userfile_handle) {
+        $newmail_userfile_filesize = filesize($newmail_userfile_location);
+        $newmail_userfile_contents = fread($newmail_userfile_handle,$newmail_userfile_filesize);
+        fclose ($newmail_userfile_handle);
 
-            // user prefs use only integer values to store file type
-            switch($newmail_userfile_type) {
-            case SM_NEWMAIL_FILETYPE_WAV:
-                // wav file
-                $newmail_userfile_contenttype='audio/x-wav';
-                break;
-            case SM_NEWMAIL_FILETYPE_MP3:
-                // mp3 file
-                $newmail_userfile_contenttype='audio/mpeg';
-                break;
-            case SM_NEWMAIL_FILETYPE_OGG:
-                // ogg file
-                $newmail_userfile_contenttype='application/ogg';
-                break;
-            case SM_NEWMAIL_FILETYPE_SWF:
-                // flash file
-                $newmail_userfile_contenttype='application/x-shockwave-flash';
-                break;
-            case SM_NEWMAIL_FILETYPE_SVG:
-                // svg file
-                $newmail_userfile_contenttype='image/svg+xml';
-                break;
-            default:
-                // none of above
-                $newmail_userfile_contenttype='unknown';
-            }
+        // user prefs use only integer values to store file type
+        switch($newmail_userfile_type) {
+        case SM_NEWMAIL_FILETYPE_WAV:
+            // wav file
+            $newmail_userfile_contenttype='audio/x-wav';
+            break;
+        case SM_NEWMAIL_FILETYPE_MP3:
+            // mp3 file
+            $newmail_userfile_contenttype='audio/mpeg';
+            break;
+        case SM_NEWMAIL_FILETYPE_OGG:
+            // ogg file
+            $newmail_userfile_contenttype='application/ogg';
+            break;
+        case SM_NEWMAIL_FILETYPE_SWF:
+            // flash file
+            $newmail_userfile_contenttype='application/x-shockwave-flash';
+            break;
+        case SM_NEWMAIL_FILETYPE_SVG:
+            // svg file
+            $newmail_userfile_contenttype='image/svg+xml';
+            break;
+        default:
+            // none of above
+            $newmail_userfile_contenttype='unknown';
+        }
 
-            // make sure that media file is in correct format
-            $newmail_userfile_extension=newmail_detect_filetype($newmail_userfile_contents,$newmail_userfile_contenttype);
+        // make sure that media file is in correct format
+        $newmail_userfile_extension=newmail_detect_filetype($newmail_userfile_contents,$newmail_userfile_contenttype);
 
-            // last check before sending file contents to browser.
-            if ($newmail_userfile_extension!=false) {
-                $newmail_send_filename='mediafile.' . $newmail_userfile_extension;
-                header ('Content-Disposition: inline; filename="' . $newmail_send_filename . '"');
-                header('Content-Type: "' . $newmail_userfile_contenttype .'"; ' .
-                       'name="' . $newmail_send_filename . '"');
-                header('Content-Length: ' . $newmail_userfile_filesize );
-                echo $newmail_userfile_contents;
-                exit;
-            } // file type detection failed
-        } // failed to open userfile
-    } // userfile is missing or preferences don't store file type.
+        // last check before sending file contents to browser.
+        if ($newmail_userfile_extension!=false) {
+            $newmail_send_filename='mediafile.' . $newmail_userfile_extension;
+            header ('Content-Disposition: inline; filename="' . $newmail_send_filename . '"');
+            header('Content-Type: "' . $newmail_userfile_contenttype .'"; ' .
+                   'name="' . $newmail_send_filename . '"');
+            header('Content-Length: ' . $newmail_userfile_filesize );
+            echo $newmail_userfile_contents;
+            exit;
+        } // file type detection failed
+    } // failed to open userfile
+} // userfile is missing or preferences don't store file type.
 // maybe we should send some error code
 ?>