Add a lot of comments

Signed-off-by: Florian Pritz <bluewind@xssn.at>

2 files changed, 34 insertions, 1 deletions

diff --git a/system/application/controllers/file.php b/system/application/controllers/file.php
index 2005d21bd..6d99312b8 100644
--- a/system/application/controllers/file.php
+++ b/system/application/controllers/file.php
@@ -8,7 +8,6 @@
  */
 
 class File extends Controller {
-  // TODO: Add comments
 
   function __construct()
   {
@@ -19,6 +18,7 @@ class File extends Controller {
     $this->file_mod->var->cli_client =& $this->var->cli_client;
     $this->var->latest_client = trim(file_get_contents(FCPATH.'data/client/latest'));
 
+    // official client uses "fb-client/$version" as useragent
     if (strpos($_SERVER['HTTP_USER_AGENT'], 'fb-client') !== false) {
       $client_version = substr($_SERVER['HTTP_USER_AGENT'], 10);
       if ($this->var->latest_client != $client_version)  {
@@ -32,6 +32,9 @@ class File extends Controller {
 
   function index()
   {
+    // Try to guess what the user would like to do.
+    // File uploads should be checked first because they are usually big and
+    // take quite some time to upload.
     if(isset($_FILES['file'])) {
       $this->do_upload();
     } elseif ($this->input->post('content')) {
@@ -58,11 +61,14 @@ class File extends Controller {
     $this->load->view('file/footer', $data);
   }
 
+  // Allow CLI clients to query the server for the maxium filesize so they can
+  // stop the upload before wasting time and bandwith
   function get_max_size()
   {
     echo $this->config->item('upload_max_size');
   }
 
+  // Allow users to delete IDs if their password matches the one used when uploading
   function delete()
   {
     $id = $this->uri->segment(3);
@@ -75,15 +81,21 @@ class File extends Controller {
     die();
   }
 
+  // Take the content from post instead of a file
+  // support textareas on the upload form
+  // XXX: This requires users of suhosin to adjust maxium post and request size
+  // TODO: merge with do_upload()
   function do_paste() 
   {
     $data = array();
     $content = $this->input->post('content')."\n";
     $extension = $this->input->post('extension');
+    // prevent empty pastes from the upload form
     if($content === "\n") {
       $this->upload_form();
       return;
     }
+    // TODO: Display nice error for cli clients
     if(strlen($content) > $this->config->item('upload_max_size')) {
       $this->load->view('file/header', $data);
       $this->load->view('file/too_big');
@@ -103,10 +115,13 @@ class File extends Controller {
     $this->file_mod->show_url($id, $extension);
   }
 
+  // Handles uploaded files
+  // TODO: merge with do_paste()
   function do_upload()
   {
     $data = array();
     $extension = $this->input->post('extension');
+    // TODO: Display nice error for cli clients
     if(!isset($_FILES['file'])) {
       $this->load->view('file/header', $data);
       $this->load->view('file/upload_error');
@@ -118,6 +133,7 @@ class File extends Controller {
       return;
     }
     $filesize = filesize($_FILES['file']['tmp_name']);
+    // TODO: Display nice error for cli clients
     if ($filesize > $this->config->item('upload_max_size')) {
       $this->load->view('file/header', $data);
       $this->load->view('file/too_big');
@@ -138,6 +154,7 @@ class File extends Controller {
     $this->file_mod->show_url($id, $extension);
   }
 
+  // Removes old files
   function cron()
   {
     if ($this->config->item('upload_max_age') == 0) return;
diff --git a/system/application/models/file_mod.php b/system/application/models/file_mod.php
index d712c7fa3..3bcbabb5e 100644
--- a/system/application/models/file_mod.php
+++ b/system/application/models/file_mod.php
@@ -14,6 +14,8 @@ class File_mod extends Model {
     parent::Model();
   }
 
+  // Returns an unused ID
+  // TODO: make threadsafe
   function new_id()
   {
     $id = $this->random_id(3,6);
@@ -62,10 +64,12 @@ class File_mod extends Model {
     }
   }
 
+  // return the folder in which the file with $hash is stored
   function folder($hash) {
     return $this->config->item('upload_path').'/'.substr($hash, 0, 3);
   }
 
+  // Returns the full path to the file with $hash
   function file($hash) {
     return $this->folder($hash).'/'.$hash;
   }
@@ -75,6 +79,7 @@ class File_mod extends Model {
     return sha1($this->config->item('passwordsalt').$password);
   }
 
+  // Returns the password submitted by the user
   function get_password()
   {
     $password = $this->input->post('password');
@@ -86,6 +91,8 @@ class File_mod extends Model {
     return 'NULL';
   }
 
+  // Add a hash to the DB
+  // TODO: Should only update not insert; see new_id()
   function add_file($hash, $id, $filename)
   {
     $mimetype = exec(FCPATH.'scripts/mimetype -b --orig-name '.escapeshellarg($filename).' '.escapeshellarg($this->file($hash)));
@@ -131,6 +138,8 @@ class File_mod extends Model {
     }
   }
 
+  // download a given hash
+  // TODO: make smaller
   function download()
   {
     $data = array();
@@ -175,6 +184,7 @@ class File_mod extends Model {
 
       $type = $filedata['mimetype'] ? $filedata['mimetype'] : exec(FCPATH.'scripts/mimetype -b --orig-name '.escapeshellarg($filedata['filename']).' '.escapeshellarg($file));
 
+      // /$mode at the end of the URL overwrites autodetection
       if (!$mode && substr_count(ltrim($this->uri->uri_string(), "/"), '/') >= 1) {
         $mode = $this->mime2extension($type);
         $mode = $this->filename2extension($filedata['filename']) ? $this->filename2extension($filedata['filename']) : $mode;
@@ -215,6 +225,7 @@ class File_mod extends Model {
             echo '<td class="numbers"><pre>';
             // only rewrite if it's fast
             // count(file($file)); isn't
+            // generate line numbers (links)
             passthru('/usr/bin/perl -ne \'print "<a href=\"#n$.\" class=\"no\" id=\"n$.\" name=\"n$.\">$.</a>\n"\' '.escapeshellarg($file));
             echo '</pre></td><td class="code"><pre>'."\n";
             $this->load->library("MemcacheLibrary");
@@ -252,6 +263,7 @@ class File_mod extends Model {
       }
       exit();
     } else {
+      // TODO: remove -controller function has been removed
       $this->load->view('file/header', $data);
       $this->load->view('file/non_existant');
       $this->load->view('file/footer');
@@ -306,6 +318,8 @@ class File_mod extends Model {
     return true;
   }
 
+  // Generate a random ID
+  // TODO: speed up
   private function random_id($min_length, $max_length)
   {
     $random = '';
@@ -324,6 +338,7 @@ class File_mod extends Model {
     return $random;
   }
 
+  // Map MIME types to extensions needed for highlighting
   function mime2extension($type)
   {
     $typearray = array(
@@ -367,6 +382,7 @@ class File_mod extends Model {
     return false;
   }
 
+  // Map special filenames to extensions
   function filename2extension($name)
   {
     $namearray = array(