[limb-svn] r5454 - 3.x/limb/toolkit/src

[svn at limb-project.com]

Author: serega
Date: 2007-04-01 15:10:50 +0400 (Sun, 01 Apr 2007)
New Revision: 5454
URL: http://fisheye.limb-project.com/changelog/limb/?cs=5454

Modified:
   3.x/limb/toolkit/src/lmbToolkit.class.php
Log:
-- better API docs for TOOLKIT package

Modified: 3.x/limb/toolkit/src/lmbToolkit.class.php
===================================================================
--- 3.x/limb/toolkit/src/lmbToolkit.class.php	2007-03-30 14:08:59 UTC (rev 5453)
+++ 3.x/limb/toolkit/src/lmbToolkit.class.php	2007-04-01 11:10:50 UTC (rev 5454)
@@ -21,8 +21,10 @@
 *  1) lmbToolkit is a Singleton
 *  2) lmbToolkit consists of so called tools. Tools is an object of any class that supports {@link lmbToolkitTools} interface
 *  3) lmbToolkit redirects all non existing methods via magic __call to tools if these methods were named in $tools :: getToolsSignatures() result.
+*  4) lmbToolkit also acts as a registry. You can put any data into toolkit and get them out at any place of your application
 * As a result we get an easily accessible object that we can extend with any methods we need.
 * We can also replace one tools with others thus we can return to client code completely different results from the same toolkit methods.
+* lmbToolkit also supports magic getters and setters. Say you have tools with getVar() method and you call $toolkit->get('var') then tools->getVar() will be actually called
 * Example of usage:
 * <code>
 * lmb_require('limb/net/src/lmbNetTools.class.php');
@@ -31,8 +33,11 @@
 * lmbToolkit :: merge(new lmbDbTools());
 * // somethere in client code
 * $toolkit = lmbToolkit :: instance();
+* $toolkit->set('my_var', $value)'
 * $request = $toolkit->getRequest(); // supported by lmbNetTools
+* $same_request = $toolkit->get('requets'); // will delegate to getRequest()
 * $db_connection = $toolkit->getDefaultDbConnection(); // supported by lmbDbTools
+* $toolkit->get('my_var'); // returns $value value
 * </code>
 * @see lmbToolkitTools
 */
@@ -55,6 +60,10 @@
   */
   protected $signatures_loaded = false;
 
+  /**
+  * Sets new tools object and clear signatures cache
+  * @param lmbToolkitTools
+  */
   protected function setTools($tools)
   {
     $this->tools = $tools;
@@ -62,6 +71,10 @@
     $this->signatures_loaded = false;
   }
 
+  /**
+  * Sets new set of toolkit data
+  * @param array
+  */
   protected function setProperties($properties)
   {
     $this->properties = $properties;
@@ -71,7 +84,7 @@
   * Returns toolkit instance. Takes instance from {@link lmbRegistry)
   * If instance is not initialized yet - creates one with empty tools
   * @see lmbRegistry
-  * @return lmbToolkit
+  * @return lmbToolkit The only instance of lmbToolkit class
   */
   static function instance()
   {
@@ -105,7 +118,7 @@
   /**
   * Fills toolkit instance with suggested tools and registers this tools in {@ling lmbRegisty}
   * @see lmbRegistry
-  * @return lmbToolkit
+  * @return lmbToolkit The only instance of lmbToolkit class
   */
   static function setup($tools)
   {
@@ -121,7 +134,7 @@
   /**
   * Save current tools object in registry stack and creates a new one using currently saved empty copy of tools object
   * @see lmbRegistry :: save()
-  * @return lmbToolkit
+  * @return lmbToolkit The only instance of lmbToolkit class
   */
   static function save()
   {
@@ -147,7 +160,7 @@
 
   /**
   * Restores previously saved tools object instance from {@link lmbRegistry} stack and sets this tools into toolkit instance
-  * @return lmbToolkit
+  * @return lmbToolkit The only instance of lmbToolkit class
   */
   static function restore()
   {
@@ -170,7 +183,7 @@
   * Extends current tools with new tools
   * Merges tools together using {@link lmbCompositeNonItersectingToolkitTools} that doesn't allow tools methods intersection
   * @see lmbCompositeNonItersectingToolkitTools
-  * @return lmbToolkit
+  * @return lmbToolkit The only instance of lmbToolkit class
   */
   static function extend($tools)
   {
@@ -184,7 +197,7 @@
   * Extends current tools with new tools
   * Merges tools together using {@link lmbCompositeToolkitTools}
   * @see lmbCompositeToolkitTools
-  * @return lmbToolkit
+  * @return lmbToolkit The only instance of lmbToolkit class
   */
   static function merge($tools)
   {
@@ -194,6 +207,11 @@
     return self :: setup(new lmbCompositeToolkitTools($tools_copy, $tools));
   }
 
+  /**
+  * Sets variable into toolkit
+  * Checks if appropriate setter method in tools exists to delegate to
+  * @return void
+  */
   function set($var, $value)
   {
     if($method = $this->_mapPropertyToSetMethod($var))
@@ -202,6 +220,11 @@
       $this->setRaw($var, $value);
   }
 
+  /**
+  * Gets variable from toolkit
+  * Checks if appropriate getter method in tools exists to delegate to
+  * @return void
+  */
   function get($var)
   {
     if($method = $this->_mapPropertyToGetMethod($var))
@@ -210,11 +233,21 @@
       return $this->getRaw($var);
   }
 
+  /**
+  * Sets variable from toolkit
+  * Doesn't check if appropriate setter method in tools exists to delegate to
+  * @return void
+  */
   function setRaw($var, $value)
   {
     $this->properties[$var] = $value;
   }
 
+  /**
+  * Gets variable from toolkit
+  * Doesn't check if appropriate getter method in tools exists to delegate to
+  * @return void
+  */
   function getRaw($var)
   {
     if(isset($this->properties[$var]))