improved phpdoc

AjaxImageGenerator.class.php

@@ -1,4 +1,8 @@
 <?php 
+/**
+ * Contains AjaxImageGenerator class definition
+ */
+
 
 /**
  * Hooks the ImageGenerator class to admin-ajax action

ClassAutoloader.class.php

@@ -1,4 +1,8 @@
 <?php
+/**
+ * Contains the ClassAutoloader class definitions
+ */
+
 /**
  * Autoload needed classes
  * @author etessore
@@ -11,8 +15,15 @@
  */
 class ClassAutoloader {
 	const WORDPRESS_THEME_UTILS_CLASS_DIR = 'classes';
+
+	/**
+	 * @var array stores the path the system will scan for files
+	 */
 	public $loading_template;
 
+	/**
+	 * Initializes the autoloader
+	 */
 	public function __construct() {
 		$this
 			// First search in the child theme dir

DebugUtils.class.php

@@ -1,4 +1,7 @@
 <?php 
+/**
+ * Stores DebugUtils class definition
+ */
 
 /**
  * Utils to debug the code while writing it.
@@ -56,6 +59,8 @@ public function __construct(){
 	}
 
 	/**
+	 * This object is a Singleton.
+	 * This method gets the instance of it.
 	 * @return DebugUtils the single instance of the class
 	 */
 	public static function get_instance(){
@@ -78,6 +83,7 @@ public function set_level($level){
 	}
 
 	/**
+	 * Retrieves the current level of echo
 	 * @return the current level of echo
 	 */
 	public function get_level(){

DefaultAssets.class.php

@@ -1,14 +1,27 @@
 <?php 
+/**
+ * Contains the DefaultAssets class
+ */
 
 /**
  * Register some useful assets in WordPress
  * @author etessore
  * @version 1.0.1
  */
 class DefaultAssets{
+	/**
+	 * @var arrary manages the list of css and js 
+	 */
 	private $assets = array('css' => array(), 'js' => array());
+
+	/**
+	 * @var array stores infos on path and uri
+	 */
 	private $base_dir = array();
 
+	/**
+	 * Register some assets and hooks into WP
+	 */
 	function __construct(){
 		$this
 			->register_standard()
@@ -104,6 +117,11 @@ public function register_standard(){
 	/**
 	 * Adds a javascript to the current set
 	 * @see @link http://codex.wordpress.org/Function_Reference/wp_register_script
+	 * @param string $handle Script name
+	 * @param string $src Script url
+	 * @param array $deps (optional) Array of script names on which this script depends
+	 * @param string|bool $ver (optional) Script version (used for cache busting), set to NULL to disable
+	 * @param bool $in_footer (optional) Whether to enqueue the script before </head> or before </body>
 	 * @return DefaultAssets $this for chainability
 	 */
 	public function add_js($handle, $src, $deps = array(), $ver = null, $in_footer = false){
@@ -120,6 +138,13 @@ public function add_js($handle, $src, $deps = array(), $ver = null, $in_footer =
 	/**
 	 * Adds a css to the current set
 	 * @see @link http://codex.wordpress.org/Function_Reference/wp_register_style
+	 * @param string $handle Name of the stylesheet.
+	 * @param string|bool $src Path to the stylesheet from the root directory of WordPress. Example: '/css/mystyle.css'.
+	 * @param array $deps Array of handles of any stylesheet that this stylesheet depends on.
+	 *  (Stylesheets that must be loaded before this stylesheet.) Pass an empty array if there are no dependencies.
+	 * @param string|bool $ver String specifying the stylesheet version number. Set to NULL to disable.
+	 *  Used to ensure that the correct version is sent to the client regardless of caching.
+	 * @param string $media The media for which this stylesheet has been defined.
 	 * @return DefaultAssets $this for chainability
 	 */
 	public function add_css($handle, $src, $deps = array(), $ver = null, $media = false){

EscapeRoute.class.php

@@ -1,4 +1,8 @@
 <?php 
+/**
+ * stores the EscapeRoute class definition
+ */
+
 /**
  * Manages the navigation links on a 404 page
  * @author etessore
@@ -9,9 +13,24 @@
  * 	moved from ThemeHelpers to HtmlHelper class
  */
 class EscapeRoute{
+	/**
+	 * @var array the list of link to be printed in case of 404
+	 */
 	public $links = array();
+
+	/**
+	 * @var string the substitution template
+	 */
 	public $tpl;
+
+	/**
+	 * @var SubstitutionTemplate the substitution engine
+	 */
 	public $templates;
+
+	/**
+	 * @var string the list separator
+	 */
 	public $list_separator = '';
 
 	/**
@@ -75,6 +94,7 @@ public function set_separator($separator){
 	}
 
 	/**
+	 * Renders the list of anchors
 	 * @return the rendered the list of anchors
 	 */
 	protected function render_list(){
@@ -91,6 +111,7 @@ protected function render_list(){
 	}
 
 	/**
+	 * Retrieves the markup
 	 * @returns the markup
 	 */
 	public function get_markup(){

FeatureWithAssets.class.php

@@ -1,4 +1,9 @@
 <?php 
+/**
+ * Contains the FeatureWithAssets class
+ */
+
+
 /**
  * Manages the assets loading for a feature.
  * 

ForceDownload.class.php

@@ -1,4 +1,7 @@
 <?php 
+/**
+ * Contains ForceDownload class definition
+ */
 
 /**
  * Force an attachment to be downloaded
@@ -11,7 +14,6 @@ class ForceDownload{
 	 * Enables the force to download feature
 	 * @param bool $priv
 	 * @param bool $nopriv
-	 * @param string $request_field
 	 */
 	public function __construct($priv=true, $nopriv=true){
 		if($priv) add_action('wp_ajax_download', array(&$this, 'force_download'));
@@ -51,10 +53,12 @@ public static function check_request(){
 	}
 
 	/**
-	 *
-	 * @param int $id
-	 * @param string $label
-	 * @param array|string $parms @see
+	 * Calculates the url for the attachment with id $id
+	 * @param int $id the attachment id
+	 * @param string $label the text inside the <a> tag
+	 * @param array $parms additional parameters for the <a> tag 
+	 * @see ThemeHelpers::anchor()
+	 * @return string an <a> tag
 	 */
 	public function force_download_anchor($id, $label, $parms){
 		return ThemeHelpers::anchor(admin_url('admin-ajax.php').'?action=download&id='.$id, $label, $parms);

GMapDataRetriever.class.php

@@ -1,18 +1,19 @@
 <?php 
+/**
+ * Stores the GMapDataRetriever class definition
+ */
+
 /**
  * Retrieves GMaps data for the gmap.js integration
  * @author etessore
  * @version 1.0
  */
 class GMapDataRetriever {
-	private $map_data;
-
 	/**
-	 * 
+	 * @var array stores some map data
 	 */
-	public function __construct(){
-		//$this->use_simple_fields();
-	}
+	private $map_data;
+
 
 	/**
 	 * Set the map data to the given set
@@ -67,16 +68,24 @@ public function use_simple_fields(){
 			);
 	}
 
+	/*
 	public function use_shared_datastore(){
 		
-	}
-
+	}*/
 
 
+	/**
+	 * Get a <script> tag with a JSON variable in it.
+	 * @example GMapDataRetriever.example.json
+	 * @return string
+	 */
 	function get_script_content(){
 		return HtmlHelper::script('var map_info = ' . json_encode($this->map_data));
 	}
 
+	/**
+	 * Prints the <scrpt> tag generated by get_script_content to the DOM
+	 */
 	function the_script(){
 		echo $this->get_script_content();
 	}

GMapDataRetriever.example.json

@@ -0,0 +1,15 @@
+{
+   "center":{
+      "lat":45.433976164602,
+      "lng":12.342536151409
+   },
+   "point":{
+      "lat":45.433976164602,
+      "lng":12.342536151409
+   },
+   "zoom":14,
+   "type":"ROADMAP",
+   "title":"Hotel Londra Palace",
+   "content":"<p>Riva degli Schiavoni, 4171<br \/>\n30122 Venice, Italy<br \/>\n+39 041 520 0533<br \/>\n[email protected]<br \/>\n<a class=\"book-action\" href=\"javascript:;\">book<\/a><\/p>\n",
+   "book_trans":"book"
+}

GalleryHelper.class.php

@@ -1,13 +1,14 @@
 <?php 
-
+/**
+ * Stores the GalleryHelper class definition
+ */
 /**
  * Manages the markup for a generic set of images
  * Extend this with your nice and candy classes!
  * @author etessore
  * @version 1.0.2
  */
 abstract class GalleryHelper extends FeatureWithAssets{
-	public $textdomain = 'theme';
 
 	/**
 	 * @var string the unique id for the current gallery
@@ -84,6 +85,7 @@ public function set_template($tpl){
 
 	/**
 	 * Set the static markup; ie: prev\next\loading divs
+	 * @param string $key the string has to be substituted 
 	 * @param string $markup html markup
 	 * @return GalleryHelper $this for chainability
 	 */
@@ -306,6 +308,7 @@ protected function get_image_description($index){
 
 
 	/**
+	 * Retrieves the markup for the current gallery
 	 * @return the markup for the current gallery
 	 */
 	abstract public function get_markup();

GaussianMath.class.php

@@ -1,21 +1,36 @@
 <?php 
 /**
- * The following object is used to compute numbers with a guassian distribution
+ * sstores the GaussianMath class definition
+ */
+
+/**
+ * The following object is used to compute numbers with a gaussian distribution
  * @link http://us.php.net/manual/en/function.rand.php#53784
  */
 class GaussianMath{
 
+	/**
+	 * Gets a random number in a gaussian distribution
+	 */
 	public function gauss(){
 		$x = $this->random_0_1();
 		$y = $this->random_0_1();
 
 		return sqrt(-2 * log($x)) * cos(2 * pi() * $y);
 	}
 
+	/**
+	 * Get an ms value
+	 * @param double $m
+	 * @param double $s
+	 */
 	public function gauss_ms($m = 0.0, $s = 1.0){
 		return $this->gauss() * $s + $m;
 	}
 
+	/**
+	 * Gets a random float between 0 and 1
+	 */
 	public function random_0_1(){
 		return (float) rand() / (float) getrandmax();
 	}

GeneratorDictionary.class.php

@@ -1,4 +1,7 @@
 <?php 
+/**
+ * Stores GeneratorDictionary class definitions
+ */
 
 /**
  * Maintans a set of words for a sentences generator
@@ -8,9 +11,19 @@
  * insertion and deletion will be more efficent
  */
 class GeneratorDictionary{
+	/**
+	 * @var array a list of usable words
+	 */
 	private $words;
+
+	/**
+	 * @var int the number of usable words
+	 */
 	private $count;
 
+	/**
+	 * Initializes the dictionary
+	 */
 	public function __construct(){
 		$this->count = 0;
 		$this
@@ -45,13 +58,15 @@ public function remove_word($word){
 	}
 
 	/**
+	 * Retrieves all the usable words of this dictionary
 	 * @return the full set of words
 	 */
 	public function get_all_words(){
 		return $this->words;
 	}
 
 	/**
+	 * Retrieves the number of usable words in this dictionary
 	 * @return the number of words in the current dictionary
 	 */
 	public function number_of_words(){