From e23649173d2a54143f63f7addcc4c7879cb5bd94 Mon Sep 17 00:00:00 2001
From: drigato <denise.rigato@sourcefabric.org>
Date: Thu, 30 Oct 2014 12:12:47 -0400
Subject: [PATCH] Added comments to CcFiles and CloudFile classes.

---
 .../application/models/airtime/CcFiles.php    | 14 +++++++++++++-
 .../application/models/airtime/CloudFile.php  | 19 ++++++++++++++++---
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/airtime_mvc/application/models/airtime/CcFiles.php b/airtime_mvc/application/models/airtime/CcFiles.php
index 8bc02a25f..956e8181e 100644
--- a/airtime_mvc/application/models/airtime/CcFiles.php
+++ b/airtime_mvc/application/models/airtime/CcFiles.php
@@ -71,6 +71,9 @@ class CcFiles extends BaseCcFiles {
         return $response;
     }
     
+    /**
+     * Returns the file size in bytes.
+     */
     public function getFileSize()
     {
         return filesize($this->getAbsoluteFilePath());
@@ -82,11 +85,17 @@ class CcFiles extends BaseCcFiles {
         return $info['filename'];
     }
     
+    /**
+     * Returns the file's absolute file path stored on disk.
+     */
     public function getURLForTrackPreviewOrDownload()
     {
         return $this->getAbsoluteFilePath();
     }
     
+    /**
+     * Returns the file's absolute file path stored on disk.
+     */
     public function getAbsoluteFilePath()
     {
         $music_dir = Application_Model_MusicDir::getDirByPK($this->getDbDirectory());
@@ -99,6 +108,9 @@ class CcFiles extends BaseCcFiles {
         return Application_Common_OsPath::join($directory, $filepath);
     }
     
+    /**
+     * Checks if the file is a regular file that can be previewed and downloaded.
+     */
     public function isValidFile()
     {
         return is_file($this->getAbsoluteFilePath());
@@ -106,7 +118,7 @@ class CcFiles extends BaseCcFiles {
     
     /**
      * 
-     * Deletes the file from the stor directory
+     * Deletes the file from the stor directory on disk.
      */
     public function deletePhysicalFile()
     {
diff --git a/airtime_mvc/application/models/airtime/CloudFile.php b/airtime_mvc/application/models/airtime/CloudFile.php
index cba99055d..a31660403 100644
--- a/airtime_mvc/application/models/airtime/CloudFile.php
+++ b/airtime_mvc/application/models/airtime/CloudFile.php
@@ -5,7 +5,9 @@ require_once 'Amazon_S3.php';
 /**
  * Skeleton subclass for representing a row from the 'cloud_file' table.
  *
- *
+ * Each cloud_file has a corresponding cc_file referenced as a foreign key.
+ * The file's metadata is stored in the cc_file table. This, cloud_file,
+ * table represents files that are stored on Amazon S3.
  *
  * You should add additional methods to this class to meet the
  * application requirements.  This class will only be generated as
@@ -16,6 +18,11 @@ require_once 'Amazon_S3.php';
 class CloudFile extends BaseCloudFile
 {
 
+    /**
+     * Returns a signed URL to the file's object on Amazon S3. Since we are
+     * requesting the file's object via this URL, it needs to be signed because
+     * all objects stored on Amazon S3 are private.
+     */
     public function getURLForTrackPreviewOrDownload()
     {
         return $this->getAbsoluteFilePath()."?".$this->getAuthenticationParams();
@@ -23,7 +30,7 @@ class CloudFile extends BaseCloudFile
     
     /**
      * 
-     * Enter description here ...
+     * Returns a url to the file's object on Amazon S3.
      */
     public function getAbsoluteFilePath()
     {
@@ -62,6 +69,9 @@ class CloudFile extends BaseCloudFile
         return "AWSAccessKeyId=$s3_access_key&Expires=$expires&Signature=$signature";
     }
     
+    /**
+     * Returns the file size in bytes.
+     */
     public function getFileSize()
     {
         $amazon_s3 = new Amazon_S3();
@@ -80,6 +90,9 @@ class CloudFile extends BaseCloudFile
         return $this->getDbFilepath();
     }
     
+    /**
+     * Checks if the file is a regular file that can be previewed and downloaded.
+     */
     public function isValidFile()
     {
         $ch = curl_init();
@@ -125,7 +138,7 @@ class CloudFile extends BaseCloudFile
     
     /**
      * 
-     * Deletes the cloud_file's 'parent' object before itself
+     * Deletes the cc_file and cloud_file entries from the database.
      */
     public function delete(PropelPDO $con = NULL)
     {