added many function comments for phpDocumentor

git-svn-id: file:///var/lib/svn/phpfspot/trunk@210 fa6a889d-dae6-447d-9e79-4ba9a3039384

2 files changed, 242 insertions, 9 deletions

diff --git a/phpfspot.class.php b/phpfspot.class.php
index 878226b..265fa1d 100644
--- a/phpfspot.class.php
+++ b/phpfspot.class.php
@@ -34,6 +34,13 @@ class PHPFSPOT {
    var $tags;
    var $avail_tags;
 
+   /**
+    * class constructor
+    *
+    * this function will be called on class construct
+    * and will check requirements, loads configuration,
+    * open databases and start the user session
+    */
    public function __construct()
    {
       /* Check necessary requirements */
@@ -76,6 +83,15 @@ class PHPFSPOT {
 
    } // __destruct()
 
+   /**
+    * show - generate html output
+    *
+    * this function can be called after the constructor has
+    * prepared everyhing. it will load the index.tpl smarty
+    * template. if necessary it will registere pre-selects
+    * (photo index, photo, tag search, date search) into
+    * users session.
+    */
    public function show()
    {
       $this->tmpl->assign('searchfor', $_SESSION['searchfor']);
@@ -116,7 +132,6 @@ class PHPFSPOT {
             $this->tmpl->show("export.tpl");
             return;
             break;
-
       }
 
       $this->tmpl->assign('from_date', $this->get_calendar('from'));
@@ -127,9 +142,19 @@ class PHPFSPOT {
 
    } // show()
 
+   /**
+    * get_tags - grab all tags of f-spot's database
+    *
+    * this function will get all available tags from
+    * the f-spot database and store them within two
+    * arrays within this clase for later usage. in
+    * fact, if the user requests (hide_tags) it will
+    * opt-out some of them.
+    *
+    * this function is getting called once by show()
+    */
    private function get_tags()
    {
-   
       $this->avail_tags = Array();
       $count = 0;
    
@@ -157,6 +182,12 @@ class PHPFSPOT {
 
    } // get_tags()
 
+   /** 
+    * extract all photo details
+    * 
+    * retrieve all available details from f-spot's
+    * database and return them as object
+    */
    public function get_photo_details($idx)
    {
       $result = $this->db->db_query("
@@ -169,6 +200,13 @@ class PHPFSPOT {
 
    } // get_photo_details
 
+   /**
+    * returns aligned photo names 
+    *
+    * this function returns aligned (length) names for
+    * an specific photo. If the length of the name exceeds
+    * $limit the name will be shrinked (...)
+    */
    public function getPhotoName($idx, $limit = 0)
    {
       if($details = $this->get_photo_details($idx)) {
@@ -181,24 +219,43 @@ class PHPFSPOT {
 
    } // getPhotoName()
 
+   /**
+    * translate f-spoth photo path
+    * 
+    * as the full-qualified path recorded in the f-spot database
+    * is usally not the same as on the webserver, this function
+    * will replace the path with that one specified in the cfg
+    */
    public function translate_path($path, $width = 0)
    {  
       return str_replace($this->cfg->path_replace_from, $this->cfg->path_replace_to, $path);
 
    } // translate_path
 
+   /**
+    * control HTML ouput for a single photo
+    *
+    * this function provides all the necessary information
+    * for the single photo template.
+    */
    public function showPhoto($photo)
    {
+      /* get all photos from the current photo selection */
       $all_photos = $this->getPhotoSelection();
       $count = count($all_photos);
 
       for($i = 0; $i < $count; $i++) {
          
-         if($get_next) {
+         // $get_next will be set, when the photo which has to
+         // be displayed has been found - this means that the
+         // next available is in fact the NEXT image (for the
+         // navigation icons) 
+         if(isset($get_next)) {
             $next_img = $all_photos[$i];
             break;
          }
 
+         /* the next photo is our NEXT photo */
          if($all_photos[$i] == $photo) {
             $get_next = 1;
          }
@@ -235,6 +292,7 @@ class PHPFSPOT {
          $thumb_path = $this->cfg->base_path ."/thumbs/". $this->cfg->photo_width ."_". $this->getMD5($photo);
       }
 
+      /* get f-spot database meta information */
       $meta = $this->get_meta_informations($orig_path);
 
       /* If EXIF data are available, use them */
@@ -249,8 +307,8 @@ class PHPFSPOT {
       $meta_make = isset($meta['Make']) ? $meta['Make'] ." ". $meta['Model'] : "n/a";
       $meta_size = isset($meta['FileSize']) ? round($meta['FileSize']/1024, 1) ."kbyte" : "n/a";
 
-      $current_tags = $this->getCurrentTags();
       $extern_link = "index.php?mode=showp&id=". $photo;
+      $current_tags = $this->getCurrentTags();
       if($current_tags != "") {
          $extern_link.= "&tags=". $current_tags;
       }
@@ -300,6 +358,13 @@ class PHPFSPOT {
 
    } // showPhoto()
 
+   /**
+    * all available tags and tag cloud
+    *
+    * this function outputs all available tags (time ordered)
+    * and in addition output them as tag cloud (tags which have
+    * many photos will appears more then others)
+    */
    public function getAvailableTags()
    {
       $result = $this->db->db_query("
@@ -355,6 +420,13 @@ class PHPFSPOT {
 
    } // getAvailableTags()
 
+   /**
+    * output all selected tags
+    *
+    * this function output all tags which have been selected
+    * by the user. the selected tags are stored in the 
+    * session-variable $_SESSION['selected_tags']
+    */
    public function getSelectedTags()
    {
       $output = "";
@@ -371,6 +443,13 @@ class PHPFSPOT {
 
    } // getSelectedTags()
 
+   /**
+    * add tag to users session variable
+    *
+    * this function will add the specified to users current
+    * tag selection. if a date search has been made before
+    * it will be now cleared
+    */
    public function addTag($tag)
    {
       // if the result of a date search are displayed, reset them
@@ -384,6 +463,12 @@ class PHPFSPOT {
    
    } // addTag()
 
+   /**
+    * remove tag to users session variable
+    *
+    * this function removes the specified tag from
+    * users current tag selection
+    */
    public function delTag($tag)
    {
       if(isset($_SESSION['selected_tags'])) {
@@ -394,6 +479,12 @@ class PHPFSPOT {
 
    } // delTag()
 
+   /**
+    * reset tag selection
+    *
+    * if there is any tag selection, it will be
+    * deleted now
+    */
    public function resetTags()
    {
       if(isset($_SESSION['selected_tags']))
@@ -401,6 +492,12 @@ class PHPFSPOT {
 
    } // resetTags()
 
+   /**
+    * reset single photo
+    *
+    * if a specific photo was requested (external link)
+    * unset the session variable now
+    */
    public function resetPhotoView()
    {
       if(isset($_SESSION['current_photo']))
@@ -408,6 +505,12 @@ class PHPFSPOT {
 
    } // resetPhotoView();
 
+   /**
+    * reset tag search
+    *
+    * if any tag search has taken place, reset
+    * it now
+    */
    public function resetTagSearch()
    {
       if(isset($_SESSION['searchfor']))
@@ -415,6 +518,12 @@ class PHPFSPOT {
 
    } // resetTagSearch()
 
+    /**
+    * reset date search
+    *
+    * if any date search has taken place, reset
+    * it now
+    */
    public function resetDateSearch()
    {
       if(isset($_SESSION['from_date']))
@@ -424,6 +533,14 @@ class PHPFSPOT {
 
    } // resetDateSearch();
 
+   /**
+    * return all photo according selection
+    *
+    * this function returns all photos based on
+    * the tag-selection, tag- or date-search.
+    * the tag-search also has to take care of AND
+    * and OR conjunctions
+    */
    public function getPhotoSelection()
    {  
       $matched_photos = Array();
@@ -541,6 +658,12 @@ class PHPFSPOT {
 
    } // getPhotoSelection()
 
+    /**
+    * control HTML ouput for photo index
+    *
+    * this function provides all the necessary information
+    * for the photo index template.
+    */
    public function showPhotoIndex()
    {
       $photos = $this->getPhotoSelection();
@@ -727,6 +850,9 @@ class PHPFSPOT {
 
    } // showPhotoIndex()
 
+   /**
+    * show credit template
+    */
    public function showCredits()
    {
       $this->tmpl->assign('version', $this->cfg->version);
@@ -735,6 +861,14 @@ class PHPFSPOT {
 
    } // showCredits()
 
+   /**
+    * create_thumbnails for the requested width
+    *
+    * this function creates image thumbnails of $orig_image
+    * stored as $thumb_image. It will check if the image is
+    * in a supported format, if necessary rotate the image
+    * (based on EXIF orientation meta headers) and re-sizing.
+    */
    public function create_thumbnail($orig_image, $thumb_image, $width)
    {  
       if(!file_exists($orig_image)) {
@@ -870,12 +1004,22 @@ class PHPFSPOT {
 
    } // create_thumbnail()
 
+   /**
+    * return all exif meta data from the file
+    */
    public function get_meta_informations($file)
    {
       return exif_read_data($file);
 
    } // get_meta_informations()
 
+   /**
+    * create phpfspot own sqlite database
+    *
+    * this function creates phpfspots own sqlite database
+    * if it does not exist yet. this own is used to store
+    * some necessary informations (md5 sum's, ...).
+    */
    public function check_config_table()
    {
       // if the config table doesn't exist yet, create it
@@ -961,6 +1105,12 @@ class PHPFSPOT {
 
    } // gen_thumb()
 
+   /**
+    * returns stored md5 sum for a specific photo
+    *
+    * this function queries the phpfspot database for a
+    * stored MD5 checksum of the specified photo
+    */
    public function getMD5($idx)
    {
       $result = $this->cfg_db->db_query("
@@ -977,6 +1127,9 @@ class PHPFSPOT {
       
    } // getMD5()
 
+   /**
+    * set MD5 sum for the specific photo
+    */
    private function setMD5($idx, $md5)
    {
       $result = $this->cfg_db->db_exec("
@@ -986,12 +1139,26 @@ class PHPFSPOT {
 
    } // setMD5()
 
+   /**
+    * store current tag condition
+    *
+    * this function stores the current tag condition
+    * (AND or OR) in the users session variables
+    */
    public function setTagCondition($mode)
    {
       $_SESSION['tag_condition'] = $mode;
 
    } // setTagCondition()
 
+   /** 
+    * invoke tag search 
+    *
+    * this function will return all matching tags and store
+    * them in the session variable selected_tags. 
+    * getPhotoSelection() will then only return the matching
+    * photos.
+    */
    public function startTagSearch($searchfor)
    {
       $_SESSION['searchfor'] = $searchfor;
@@ -1006,18 +1173,30 @@ class PHPFSPOT {
 
    } // startTagSearch()
 
+   /** 
+    * invoke date search 
+    *
+    * this function in fact does nothing then only setting
+    * the from- and to-date in the users session variables.
+    * the result is generated by getPhotoSelection().
+    */
    public function startDateSearch($from, $to)
    {
       $_SESSION['from_date'] = $from;
       $_SESSION['to_date'] = $to;
    }
 
+   /**
+    * rotate image
+    *
+    * this function rotates the image according the
+    * specified angel.
+    */
    private function rotateImage($img, $degrees)
    {
-      if(function_exists("imagerotate"))
+      if(function_exists("imagerotate")) {
          $img = imagerotate($img, $degrees, 0);
-      else
-      {
+      } else {
          function imagerotate($src_img, $angle)
          {
             $src_x = imagesx($src_img);
@@ -1067,7 +1246,9 @@ class PHPFSPOT {
                   }
                   break;
 
-               default: $rotate = $src_img;
+               default:
+                  $rotate = $src_img;
+                  break;
             };
 
             return $rotate;
@@ -1082,6 +1263,9 @@ class PHPFSPOT {
 
    } // rotateImage()
 
+   /**
+    * return all assigned tags for the specified photo
+    */
    private function get_photo_tags($idx)
    {
       $result = $this->db->db_query("
@@ -1101,6 +1285,9 @@ class PHPFSPOT {
 
    } // get_photo_tags()
 
+   /**
+    * create on-the-fly images with text within
+    */
    public function showTextImage($txt, $color=000000, $space=4, $font=4, $w=300)
    {
       if (strlen($color) != 6) 
@@ -1127,6 +1314,9 @@ class PHPFSPOT {
 
    } // showTextImage()
 
+   /**
+    * check if all requirements are met
+    */
    private function checkRequirements()
    {
       if(!function_exists("imagecreatefromjpeg")) {
@@ -1168,6 +1358,9 @@ class PHPFSPOT {
 
    } // _debug()
 
+   /**
+    * check if specified MIME type is supported
+    */
    public function checkifImageSupported($mime)
    {
       if(in_array($mime, Array("image/jpeg")))
@@ -1184,6 +1377,9 @@ class PHPFSPOT {
 
    } // _warning()
 
+   /**
+    * output calendard input fields
+    */
    private function get_calendar($mode)
    {
       $year = $_SESSION[$mode .'_date'] ? date("Y", strtotime($_SESSION[$mode .'_date'])) : date("Y");
@@ -1197,6 +1393,9 @@ class PHPFSPOT {
 
    } // get_calendar()
 
+   /**
+    * output calendar matrix
+    */
    public function get_calendar_matrix($year = 0, $month = 0, $day = 0)
    {
       if (!isset($year)) $year = date('Y');
@@ -1209,7 +1408,6 @@ class PHPFSPOT {
       require_once CALENDAR_ROOT.'Month/Weekdays.php';
       require_once CALENDAR_ROOT.'Day.php';
 
-
       // Build the month
       $month = new Calendar_Month_Weekdays($year,$month);
 
@@ -1273,6 +1471,9 @@ class PHPFSPOT {
 
    } // get_calendar_matrix()
 
+   /**
+    * output export page
+    */
    public function getExport($mode)
    {
       $pictures = $this->getPhotoSelection();
@@ -1312,6 +1513,9 @@ class PHPFSPOT {
 
    } // getExport()
 
+   /**
+    * return all selected tags as one string
+    */
    private function getCurrentTags()
    {
       $current_tags = "";
@@ -1324,6 +1528,9 @@ class PHPFSPOT {
 
    } // getCurrentTags()
 
+   /**
+    * return the current photo
+    */
    public function getCurrentPhoto()
    {
       if(isset($_SESSION['current_photo'])) {
@@ -1331,6 +1538,15 @@ class PHPFSPOT {
       }
    } // getCurrentPhoto()
 
+   /**
+    * tells the client browser what to do
+    *
+    * this function is getting called via AJAX by the
+    * client browsers. it will tell them what they have
+    * to do next. This is necessary for directly jumping
+    * into photo index or single photo view when the are
+    * requested with specific URLs
+    */
    public function whatToDo()
    {
       if(isset($_SESSION['selected_tags']) && !empty($_SESSION['selected_tags'])) {
@@ -1350,6 +1566,9 @@ class PHPFSPOT {
 
    } // whatToDo()
 
+   /**
+    * return the current process-user
+    */
    private function getuid()
    {
       if($uid = posix_getuid()) {
diff --git a/phpfspot_img.php b/phpfspot_img.php
index bd811e8..194b534 100644
--- a/phpfspot_img.php
+++ b/phpfspot_img.php
@@ -28,6 +28,9 @@ class PHPFSPOT_IMG {
    var $db;
    var $parent;
 
+   /**
+    * PHPFSPOT_IMG class constructor
+    */
    public function __construct()
    {
       $this->parent = new PHPFSPOT;
@@ -35,11 +38,22 @@ class PHPFSPOT_IMG {
 
    } // __construct()
 
+   /**
+    * PHPFSPOT_IMG class destructor
+    */
    public function __destruct()
    {
 
    } // __desctruct()
 
+   /**
+    * sends the specified image to the browser
+    *
+    * this function will send the specified image to 
+    * the client - in the specified width. it also try's
+    * to create on-the-fly missing thumbnails via PHPFSPOT
+    * gen_thumbs function.
+    */
    public function show($idx, $width = 0)
    {
       $details = $this->parent->get_photo_details($idx);