cleaned up phpdoc comments, added README on how to install and use it

.gitignore

@@ -1,11 +1,12 @@
 # Ignore data/ and tmp/
 data/
 tmp/
-# Ignore unit testing logs and eclipse project files
-tst/log/
-.settings/
-.buildpath
-.project
 # Ignore for safety
 .htaccess
 .htpasswd
+# Ignore unit testing logs, api docs and eclipse project files
+tst/log/
+doc/
+.settings/
+.buildpath
+.project

doc/README.md

@@ -0,0 +1,19 @@
+Generating documentation
+========================
+
+In order to generate the documentation, you will need to install the following
+packages and its dependencies:
+* phpdoc
+* graphviz
+
+Details about [installing phpDocumentor](http://phpdoc.org/docs/latest/getting-started/installing.html)
+can be found in its own documentation.
+
+Example for Debian and Ubuntu:
+    $ sudo aptitude install pear graphviz
+    $ sudo pear channel-discover pear.phpdoc.org
+    $ sudo pear install phpdoc/phpDocumentor
+
+To generate the documentation, change into the main directory and run phpdoc:
+    $ cd ZeroBin
+    $ phpdoc -d lib/ -t doc/

lib/RainTPL.php

@@ -1,8 +1,7 @@
 <?php
-
 /**
  * RainTPL
- *  -------
+ *
  * Realized by Federico Ulfo & maintained by the Rain Team
  * Distributed under GNU/LGPL 3 License
  *
@@ -10,6 +9,9 @@
  */
 
 
+/**
+ * RainTPL
+ */
 class RainTPL{
 
 	// -------------------------
@@ -25,7 +27,9 @@ class RainTPL{
 
 
 		/**
-		 * Cache directory. Is the directory where RainTPL will compile the template and save the cache
+		 * Cache directory
+		 *
+		 * Is the directory where RainTPL will compile the template and save the cache
 		 *
 		 * @var string
 		 */
@@ -33,7 +37,9 @@ class RainTPL{
 
 
 		/**
-		 * Template base URL. RainTPL will add this URL to the relative paths of element selected in $path_replace_list.
+		 * Template base URL
+		 *
+		 * RainTPL will add this URL to the relative paths of element selected in $path_replace_list.
 		 *
 		 * @var string
 		 */
@@ -41,7 +47,7 @@ class RainTPL{
 
 
 		/**
-		 * Template extension.
+		 * Template extension
 		 *
 		 * @var string
 		 */
@@ -49,10 +55,12 @@ class RainTPL{
 
 
 		/**
-		 * Path replace is a cool features that replace all relative paths of images (<img src="...">), stylesheet (<link href="...">), script (<script src="...">) and link (<a href="...">)
+		 * Should the path be replaced
+		 *
+		 * Path replace is a cool features that replace all relative paths of images (&lt;img src="..."&gt;), stylesheet (&lt;link href="..."&gt;), script (&lt;script src="..."&gt;) and link (&lt;a href="..."&gt;)
 		 * Set true to enable the path replace.
 		 *
-		 * @var unknown_type
+		 * @var boolean
 		 */
 		static $path_replace = true;
 
@@ -69,22 +77,25 @@ class RainTPL{
 		/**
 		 * You can define in the black list what string are disabled into the template tags
 		 *
-		 * @var unknown_type
+		 * @var array
 		 */
 		static $black_list = array( '\$this', 'raintpl::', 'self::', '_SESSION', '_SERVER', '_ENV',  'eval', 'exec', 'unlink', 'rmdir' );
 
 
 		/**
-		 * Check template.
+		 * Check template
+		 * 
 		 * true: checks template update time, if changed it compile them
 		 * false: loads the compiled template. Set false if server doesn't have write permission for cache_directory.
 		 *
+		 * @var bool
 		 */
 		static $check_template_update = true;
 
 
 		/**
 		 * PHP tags <? ?>
+		 *
 		 * True: php tags are enabled into the template
 		 * False: php tags are disabled into the template and rendered as html
 		 *
@@ -94,7 +105,8 @@ class RainTPL{
 
 
 		/**
-		 * Debug mode flag.
+		 * Debug mode flag
+		 *
 		 * True: debug mode is used, syntax errors are displayed directly in template. Execution of script is not terminated.
 		 * False: exception is thrown on found error.
 		 *
@@ -116,17 +128,44 @@ class RainTPL{
 		 */
 		public $var = array();
 
-		protected $tpl = array(),		// variables to keep the template directories and info
+		/**
-				  $cache = false,		// static cache enabled / disabled
+		 * variables to keep the template directories and info
-                  $cache_id = null;       // identify only one cache
+		 *
+		 * @var array
+		 */
+		protected $tpl = array();		// 
 
-                protected static $config_name_sum = array();   // takes all the config to create the md5 of the file
+		/**
+		 * static cache enabled / disabled
+		 *
+		 * @var bool
+		 */
+		protected $cache = false;
+
+		/**
+		 * identify only one cache
+		 *
+		 * @var string
+		 */
+		protected $cache_id = '';
+
+		/**
+		 * takes all the config to create the md5 of the file
+		 *
+		 * @var array the file
+		 */
+        protected static $config_name_sum = array();
 
 	// -------------------------
 
 
 
-	const CACHE_EXPIRE_TIME = 3600; // default cache expire time = hour
+	/**
+	 * default cache expire time = hour
+	 *
+	 * @const int
+	 */
+	const CACHE_EXPIRE_TIME = 3600;
 
 
 
@@ -134,11 +173,11 @@ class RainTPL{
 	 * Assign variable
 	 * eg. 	$t->assign('name','mickey');
 	 *
+	 * @access public
 	 * @param  mixed $variable_name Name of template variable or associative array name/value
 	 * @param  mixed $value value assigned to this variable. Not set if variable_name is an associative array
 	 */
-
+	public function assign( $variable, $value = null ){
-	function assign( $variable, $value = null ){
 		if( is_array( $variable ) )
 			$this->var += $variable;
 		else
@@ -152,12 +191,12 @@ class RainTPL{
 	 * eg. 	$html = $tpl->draw( 'demo', TRUE ); // return template in string
 	 * or 	$tpl->draw( $tpl_name ); // echo the template
 	 *
+	 * @access public
 	 * @param  string $tpl_name  template to load
 	 * @param  boolean $return_string  true=return a string, false=echo the template
 	 * @return string
 	 */
-
+	public function draw( $tpl_name, $return_string = false ){
-	function draw( $tpl_name, $return_string = false ){
 
 		try {
 			// compile the template if necessary and set the template filepath
@@ -211,12 +250,13 @@ class RainTPL{
 	/**
 	 * If exists a valid cache for this template it returns the cache
 	 *
+	 * @access public
 	 * @param  string $tpl_name Name of template (set the same of draw)
 	 * @param  int $expiration_time Set after how many seconds the cache expire and must be regenerated
+	 * @param  string $cache_id Suffix to be used when writing file to cache (optional)
 	 * @return string it return the HTML or null if the cache must be recreated
 	 */
-
+	public function cache( $tpl_name, $expire_time = self::CACHE_EXPIRE_TIME, $cache_id = '' ){
-	function cache( $tpl_name, $expire_time = self::CACHE_EXPIRE_TIME, $cache_id = null ){
 
         // set the cache_id
         $this->cache_id = $cache_id;
@@ -236,8 +276,12 @@ class RainTPL{
 	/**
 	 * Configure the settings of RainTPL
 	 *
+	 * @access public
+	 * @static
+	 * @param  array|string $setting array of settings or setting name
+	 * @param  mixed $value content to set in the setting (optional)
 	 */
-	static function configure( $setting, $value = null ){
+	public static function configure( $setting, $value = null ){
 		if( is_array( $setting ) )
 			foreach( $setting as $key => $value )
 				self::configure( $key, $value );
@@ -249,8 +293,14 @@ class RainTPL{
 
 
 
-	// check if has to compile the template
+	/**
-	// return true if the template has changed
+	 * Check if has to compile the template
+	 *
+	 * @access protected
+	 * @param  string $tpl_name template name to check
+	 * @throws RainTpl_NotFoundException
+	 * @return bool return true if the template has changed
+	 */
 	protected function check_template( $tpl_name ){
 
 		if( !isset($this->tpl['checked']) ){
@@ -281,7 +331,10 @@ class RainTPL{
 
 	/**
 	 * execute stripslaches() on the xml block. Invoqued by preg_replace_callback function below
+	 *
 	 * @access protected
+	 * @param string $capture
+	 * @return string
 	 */
 	protected function xml_reSubstitution($capture) {
     		return "<?php echo '<?xml ".stripslashes($capture[1])." ?>'; ?>";
@@ -289,7 +342,15 @@ class RainTPL{
 
 	/**
 	 * Compile and write the compiled template file
+	 *
 	 * @access protected
+	 * @param  string $tpl_basename
+	 * @param  string $tpl_basedir
+	 * @param  string $tpl_filename
+	 * @param  string $cache_dir
+	 * @param  string $compiled_filename
+	 * @throws RainTpl_Exception
+	 * @return void
 	 */
 	protected function compileFile( $tpl_basename, $tpl_basedir, $tpl_filename, $cache_dir, $compiled_filename ){
 
@@ -328,7 +389,11 @@ class RainTPL{
 
 	/**
 	 * Compile template
+	 *
 	 * @access protected
+	 * @param  string $template_code
+	 * @param  string $tpl_basedir
+	 * @return string
 	 */
 	protected function compileTemplate( $template_code, $tpl_basedir ){
 
@@ -369,7 +434,11 @@ class RainTPL{
 
 	/**
 	 * Compile the code
+	 *
 	 * @access protected
+	 * @param  string $parsed_code
+	 * @throws RainTpl_SyntaxException
+	 * @return string
 	 */
 	protected function compileCode( $parsed_code ){
 
@@ -585,9 +654,12 @@ class RainTPL{
 
 
 	/**
-	 * Reduce a path, eg. www/library/../filepath//file => www/filepath/file
+	 * Reduce a path
-	 * @param type $path
+	 *
-	 * @return type
+	 * eg. www/library/../filepath//file => www/filepath/file
+	 *
+	 * @param string $path
+	 * @return string
 	 */
 	protected function reduce_path( $path ){
 		$path = str_replace( "://", "@not_replace@", $path );
@@ -599,13 +671,16 @@ class RainTPL{
 
 
 	/**
-	 * replace the path of image src, link href and a href.
+	 * replace the path of image src, link href and a href
+	 * 
 	 * url => template_dir/url
 	 * url# => url
 	 * http://url => http://url
 	 *
+	 * @access protected
 	 * @param  string $html
-	 * @return string html sostituito
+	 * @param  string $tpl_basedir
+	 * @return string html substitution
 	 */
 	protected function path_replace( $html, $tpl_basedir ){
 
@@ -655,16 +730,40 @@ class RainTPL{
 
 
 
-	// replace const
+	/**
-	function const_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
+	 * replace constants
+	 *
+	 * @access public
+	 * @param  string $html
+	 * @param  string $tag_left_delimiter
+	 * @param  string $tag_right_delimiter
+	 * @param  string $php_left_delimiter (optional)
+	 * @param  string $php_right_delimiter (optional)
+	 * @param  string $loop_level (optional)
+	 * @param  string $echo (optional)
+	 * @return string
+	 */
+	public function const_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
 		// const
 		return preg_replace( '/\{\#(\w+)\#{0,1}\}/', $php_left_delimiter . ( $echo ? " echo " : null ) . '\\1' . $php_right_delimiter, $html );
 	}
 
 
 
-	// replace functions/modifiers on constants and strings
+	/**
-	function func_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
+	 * replace functions/modifiers on constants and strings
+	 *
+	 * @access public
+	 * @param  string $html
+	 * @param  string $tag_left_delimiter
+	 * @param  string $tag_right_delimiter
+	 * @param  string $php_left_delimiter (optional)
+	 * @param  string $php_right_delimiter (optional)
+	 * @param  string $loop_level (optional)
+	 * @param  string $echo (optional)
+	 * @return string
+	 */
+	public function func_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
 
 		preg_match_all( '/' . '\{\#{0,1}(\"{0,1}.*?\"{0,1})(\|\w.*?)\#{0,1}\}' . '/', $html, $matches );
 
@@ -763,7 +862,20 @@ class RainTPL{
 
 
 
-	function var_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
+	/**
+	 * replace variables
+	 *
+	 * @access public
+	 * @param  string $html
+	 * @param  string $tag_left_delimiter
+	 * @param  string $tag_right_delimiter
+	 * @param  string $php_left_delimiter (optional)
+	 * @param  string $php_right_delimiter (optional)
+	 * @param  string $loop_level (optional)
+	 * @param  string $echo (optional)
+	 * @return string
+	 */
+	public function var_replace( $html, $tag_left_delimiter, $tag_right_delimiter, $php_left_delimiter = null, $php_right_delimiter = null, $loop_level = null, $echo = null ){
 
 		//all variables
 		if( preg_match_all( '/' . $tag_left_delimiter . '\$(\w+(?:\.\${0,1}[A-Za-z0-9_]+)*(?:(?:\[\${0,1}[A-Za-z0-9_]+\])|(?:\-\>\${0,1}[A-Za-z0-9_]+))*)(.*?)' . $tag_right_delimiter . '/', $html, $matches ) ){
@@ -876,8 +988,10 @@ class RainTPL{
 	/**
 	 * Check if function is in black list (sandbox)
 	 *
+	 * @access protected
 	 * @param  string $code
-	 * @param string $tag
+	 * @throws RainTpl_SyntaxException
+	 * @return void
 	 */
 	protected function function_check( $code ){
 
@@ -904,6 +1018,7 @@ class RainTPL{
 	/**
 	 * Prints debug info about exception or passes it further if debug is disabled.
 	 *
+	 * @access protected
 	 * @param  RainTpl_Exception $e
 	 * @return string
 	 */

lib/filter.php

@@ -55,6 +55,7 @@ class filter
      * validate paste ID
      *
      * @access public
+     * @static
      * @param  string $dataid
      * @return bool
      */
@@ -68,6 +69,7 @@ class filter
      * https://crackstation.net/hashing-security.htm?=rd#slowequals
      *
      * @access public
+     * @static
      * @param  string $a
      * @param  string $b
      * @return bool

lib/persistence.php

@@ -18,6 +18,8 @@
 abstract class persistence
 {
     /**
+     * path in which to persist something
+     *
      * @access private
      * @static
      * @var    string

lib/serversalt.php

@@ -23,6 +23,8 @@
 class serversalt extends persistence
 {
     /**
+     * generated salt
+     *
      * @access private
      * @static
      * @var    string

lib/trafficlimiter.php

@@ -18,6 +18,8 @@
 class trafficlimiter extends persistence
 {
     /**
+     * time limit in seconds, defaults to 10s
+     *
      * @access private
      * @static
      * @var    int

lib/vizhash16x16.php

@@ -24,22 +24,67 @@
 
 class vizhash16x16
 {
+    /**
+     * hash values
+     *
+     * @access private
+     * @var    array
+     */
     private $VALUES;
+
+    /**
+     * index of current value
+     *
+     * @access private
+     * @var    int
+     */
     private $VALUES_INDEX;
+
+    /**
+     * image width
+     *
+     * @access private
+     * @var    int
+     */
     private $width;
+
+    /**
+     * image height
+     *
+     * @access private
+     * @var    int
+     */
     private $height;
+
+    /**
+     * salt used when generating the image
+     *
+     * @access private
+     * @var    string
+     */
     private $salt;
-    function __construct()
+
+    /**
+     * constructor
+     *
+     * @access public
+     * @return void
+     */
+    public function __construct()
     {
         $this->width  = 16;
         $this->height = 16;
         $this->salt   = serversalt::get();
     }
 
-    // Generate a 16x16 png corresponding to $text.
+    /**
-    // Input: $text (string)
+     * Generate a 16x16 png corresponding to $text.
-    // Output: PNG data. Or empty string if GD is not available.
+     *
-    function generate($text)
+     * @access public
+     * @param  string $text
+     * @return string PNG data. Or empty string if GD is not available.
+     */
+    public function generate($text)
     {
         if (!function_exists('gd_info')) return '';
 
@@ -85,7 +130,13 @@ class vizhash16x16
         return $imagedata;
     }
 
-    private function getInt() // Returns a single integer from the $VALUES array (0...255)
+    /**
+     * Returns a single integer from the $VALUES array (0...255)
+     *
+     * @access private
+     * @return int
+     */
+    private function getInt()
     {
         $v= $this->VALUES[$this->VALUES_INDEX];
         $this->VALUES_INDEX++;
@@ -93,18 +144,41 @@ class vizhash16x16
         return $v;
     }
 
-    private function getX() // Returns a single integer from the array (roughly mapped to image width)
+    /**
+     * Returns a single integer from the array (roughly mapped to image width)
+     *
+     * @access private
+     * @return int
+     */
+    private function getX()
     {
         return $this->width*$this->getInt()/256;
     }
 
-    private function getY() // Returns a single integer from the array (roughly mapped to image height)
+    /**
+     * Returns a single integer from the array (roughly mapped to image height)
+     *
+     * @access private
+     * @return int
+     */
+    private function getY()
     {
         return $this->height*$this->getInt()/256;
     }
 
-    # Gradient function taken from:
+    /**
-    # http://www.supportduweb.com/scripts_tutoriaux-code-source-41-gd-faire-un-degrade-en-php-gd-fonction-degrade-imagerie.html
+     * Gradient function
+     *
+     * taken from:
+     * http://www.supportduweb.com/scripts_tutoriaux-code-source-41-gd-faire-un-degrade-en-php-gd-fonction-degrade-imagerie.html
+     *
+     * @access private
+     * @param  resource $img
+     * @param  string $direction
+     * @param  array $color1
+     * @param  array $color2
+     * @return resource
+     */
     private function degrade($img,$direction,$color1,$color2)
     {
             if($direction=='h') { $size = imagesx($img); $sizeinv = imagesy($img); }
@@ -125,6 +199,15 @@ class vizhash16x16
             return $img;
     }
 
+    /**
+     * Draw a shape
+     *
+     * @access private
+     * @param  resource $image
+     * @param  int $action
+     * @param  int $color
+     * @return void
+     */
     private function drawshape($image,$action,$color)
     {
         switch($action%7)

lib/zerobin.php

@@ -17,12 +17,16 @@
  */
 class zerobin
 {
-    /*
+    /**
-     * @const string version
+     * version
+     *
+     * @const string
      */
     const VERSION = 'Alpha 0.19';
 
     /**
+     * configuration array
+     *
      * @access private
      * @var    array
      */
@@ -31,26 +35,34 @@ class zerobin
     );
 
     /**
+     * data
+     *
      * @access private
      * @var    string
      */
     private $_data = '';
 
     /**
+     * error message
+     *
      * @access private
      * @var    string
      */
     private $_error = '';
 
     /**
+     * status message
+     *
      * @access private
      * @var    string
      */
     private $_status = '';
 
     /**
+     * data storage model
+     *
      * @access private
-     * @var    zerobin_data
+     * @var    zerobin_abstract
      */
     private $_model;
 
@@ -60,6 +72,7 @@ class zerobin
      * initializes and runs ZeroBin
      *
      * @access public
+     * @return void
      */
     public function __construct()
     {
@@ -128,7 +141,7 @@ class zerobin
      * get the model, create one if needed
      *
      * @access private
-     * @return zerobin_data
+     * @return zerobin_abstract
      */
     private function _model()
     {

lib/zerobin/abstract.php

@@ -20,7 +20,7 @@ abstract class zerobin_abstract
 	/**
      * singleton instance
      *
-     * @access private
+     * @access protected
      * @static
      * @var zerobin
      */
@@ -49,6 +49,7 @@ abstract class zerobin_abstract
      *
      * @access public
      * @static
+     * @param  array $options
      * @return zerobin_abstract
      */
     public static function getInstance($options) {}

lib/zerobin/data.php

@@ -17,10 +17,12 @@
  */
 class zerobin_data extends zerobin_abstract
 {
-    /*
+    /**
+     * directory where data is stored
+     *
      * @access private
      * @static
-     * @var string directory where data is stored
+     * @var string
      */
     private static $_dir = 'data/';
 
@@ -29,6 +31,7 @@ class zerobin_data extends zerobin_abstract
      *
      * @access public
      * @static
+     * @param  array $options
      * @return zerobin_data
      */
     public static function getInstance($options = null)

lib/zerobin/db.php

@@ -17,31 +17,37 @@
  */
 class zerobin_db extends zerobin_abstract
 {
-    /*
+    /**
-     * @access private
+     * cache for select queries
-     * @static
+     *
-     * @var array to cache select queries
+     * @var array
      */
     private static $_cache = array();
 
-    /*
+    /**
+     * instance of database connection
+     *
      * @access private
      * @static
-     * @var PDO instance of database connection
+     * @var PDO
      */
     private static $_db;
 
-    /*
+    /**
+     * table prefix
+     *
      * @access private
      * @static
-     * @var string table prefix
+     * @var string
      */
     private static $_prefix = '';
 
-    /*
+    /**
+     * database type
+     *
      * @access private
      * @static
-     * @var string database type
+     * @var string
      */
     private static $_type = '';
 
@@ -50,6 +56,7 @@ class zerobin_db extends zerobin_abstract
      *
      * @access public
      * @static
+     * @param  array $options
      * @throws Exception
      * @return zerobin_db
      */