[REVIEW] Added API docs to Zend_Dojo_BuildLayer; removed unnecessary methods

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@16716 44c647ce-9c0f-0410-b52a-842ac1e357ba

library/Zend/Dojo/BuildLayer.php

@@ -1,16 +1,71 @@
 <?php
+/**
+ * Zend Framework
+ *
+ * LICENSE
+ *
+ * This source file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://framework.zend.com/license/new-bsd
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to license@zend.com so we can send you a copy immediately.
+ *
+ * @category   Zend
+ * @package    Zend_Dojo
+ * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ * @version    $Id: Data.php 16204 2009-06-21 18:58:29Z thomas $
+ */
+
+/**
+ * Dojo module layer and custom build profile generation support
+ * 
+ * @package    Zend_Dojo
+ * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
 class Zend_Dojo_BuildLayer
 {
+    /**
+     * Flag: whether or not to consume JS aggregated in the dojo() view 
+     * helper when generate the module layer contents
+     * @var bool
+     */
     protected $_consumeJavascript = false;
 
+    /**
+     * Flag: whether or not to consume dojo.addOnLoad events registered 
+     * with the dojo() view helper when generating the module layer file 
+     * contents
+     * @var bool
+     */
     protected $_consumeOnLoad = false;
 
+    /**
+     * Dojo view helper reference
+     * @var Zend_Dojo_View_Helper_Dojo_Container
+     */
     protected $_dojo;
 
+    /**
+     * Name of the custom layer to generate
+     * @var string
+     */
     protected $_layerName;
 
+    /**
+     * Path to the custom layer script relative to dojo.js (used when 
+     * creating the build profile)
+     * @var string
+     */
     protected $_layerScriptPath;
 
+    /**
+     * Build profile options
+     * @var array
+     */
     protected $_profileOptions = array(
         'action'        => 'release',
         'optimize'      => 'shrinksafe',
@@ -20,12 +75,25 @@ class Zend_Dojo_BuildLayer
         'cssOptimize'   => 'comments',
     );
 
-    protected $_profilePath;
-
+    /**
+     * Associative array of module/path pairs for the build profile
+     * @var array
+     */
     protected $_profilePrefixes = array();
 
+    /**
+     * Zend_View reference
+     * @var Zend_View_Interface
+     */
     protected $_view;
 
+    /**
+     * Constructor
+     * 
+     * @param  array|Zend_Config $options 
+     * @return void
+     * @throws Zend_Dojo_Exception for invalid option argument
+     */
     public function __construct($options = null)
     {
         if (null !== $options) {
@@ -39,6 +107,14 @@ class Zend_Dojo_BuildLayer
         }
     }
 
+    /**
+     * Set options
+     *
+     * Proxies to any setter that matches an option key.
+     * 
+     * @param  array $options 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function setOptions(array $options)
     {
         $methods = get_class_methods($this);
@@ -51,23 +127,48 @@ class Zend_Dojo_BuildLayer
         return $this;
     }
 
+    /**
+     * Set View object
+     * 
+     * @param  Zend_View_Interface $view 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function setView(Zend_View_Interface $view)
     {
         $this->_view = $view;
         return $this;
     }
 
+    /**
+     * Retrieve view object
+     * 
+     * @return Zend_View_Interface|null
+     */
     public function getView()
     {
         return $this->_view;
     }
 
+    /**
+     * Set dojo() view helper instance
+     * 
+     * @param  Zend_Dojo_View_Helper_Dojo_Container $helper 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function setDojoHelper(Zend_Dojo_View_Helper_Dojo_Container $helper)
     {
         $this->_dojo = $helper;
         return $this;
     }
 
+    /**
+     * Retrieve dojo() view helper instance
+     *
+     * Will retrieve it from the view object if not registered.
+     * 
+     * @return Zend_Dojo_View_Helper_Dojo_Container
+     * @throws Zend_Dojo_Exception if not registered and no view object found
+     */
     public function getDojoHelper()
     {
         if (null === $this->_dojo) {
@@ -81,6 +182,12 @@ class Zend_Dojo_BuildLayer
         return $this->_dojo;
     }
 
+    /**
+     * Set custom layer name; e.g. "custom.main"
+     * 
+     * @param  string $name 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function setLayerName($name)
     {
         if (!preg_match('/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/i', $name)) {
@@ -91,78 +198,143 @@ class Zend_Dojo_BuildLayer
         return $this;
     }
 
+    /**
+     * Retrieve custom layer name
+     * 
+     * @return string|null
+     */
     public function getLayerName()
     {
         return $this->_layerName;
     }
 
+    /**
+     * Set the path to the custom layer script
+     *
+     * Should be a path relative to dojo.js
+     * 
+     * @param  string $path 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function setLayerScriptPath($path)
     {
         $this->_layerScriptPath = (string) $path;
         return $this;
     }
 
+    /**
+     * Get custom layer script path
+     * 
+     * @return string|null
+     */
     public function getLayerScriptPath()
     {
         return $this->_layerScriptPath;
     }
 
-    public function setProfilePath($path)
-    {
-        $this->_profilePath = (string) $path;
-        return $this;
-    }
-
-    public function getProfilePath()
-    {
-        return $this->_profilePath;
-    }
-
+    /**
+     * Set flag indicating whether or not to consume JS aggregated in dojo() 
+     * view helper
+     * 
+     * @param  bool $flag 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function setConsumeJavascript($flag)
     {
         $this->_consumeJavascript = (bool) $flag;
         return $this;
     }
 
+    /**
+     * Get flag indicating whether or not to consume JS aggregated in dojo() 
+     * view helper
+     * 
+     * @return bool
+     */
     public function consumeJavascript()
     {
         return $this->_consumeJavascript;
     }
 
+    /**
+     * Set flag indicating whether or not to consume dojo.addOnLoad events 
+     * aggregated in dojo() view helper
+     * 
+     * @param  bool $flag 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function setConsumeOnLoad($flag)
     {
         $this->_consumeOnLoad = (bool) $flag;
         return $this;
     }
 
+    /**
+     * Get flag indicating whether or not to consume dojo.addOnLoad events aggregated in dojo() view helper
+     * 
+     * @return bool
+     */
     public function consumeOnLoad()
     {
         return $this->_consumeOnLoad;
     }
 
+    /**
+     * Set many build profile options at once
+     * 
+     * @param  array $options 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function setProfileOptions(array $options)
     {
         $this->_profileOptions += $options;
         return $this;
     }
 
+    /**
+     * Add many build profile options at once
+     * 
+     * @param  array $options 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function addProfileOptions(array $options)
     {
         $this->_profileOptions = $this->_profileOptions + $options;
         return $this;
     }
 
+    /**
+     * Add a single build profile option
+     * 
+     * @param  string $key 
+     * @param  value $value 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function addProfileOption($key, $value)
     {
         $this->_profileOptions[(string) $key] = $value;
         return $this;
     }
 
+    /**
+     * Is a given build profile option set?
+     * 
+     * @param  string $key 
+     * @return bool
+     */
     public function hasProfileOption($key)
     {
         return array_key_exists((string) $key, $this->_profileOptions);
     }
 
+    /**
+     * Retrieve a single build profile option
+     *
+     * Returns null if profile option does not exist.
+     * 
+     * @param  string $key 
+     * @return mixed
+     */
     public function getProfileOption($key)
     {
         if ($this->hasProfileOption($key)) {
@@ -171,11 +343,22 @@ class Zend_Dojo_BuildLayer
         return null;
     }
 
+    /**
+     * Get all build profile options
+     * 
+     * @return array
+     */
     public function getProfileOptions()
     {
         return $this->_profileOptions;
     }
 
+    /**
+     * Remove a build profile option
+     * 
+     * @param  string $name 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function removeProfileOption($name)
     {
         if ($this->hasProfileOption($name)) {
@@ -184,12 +367,26 @@ class Zend_Dojo_BuildLayer
         return $this;
     }
 
+    /**
+     * Remove all build profile options
+     * 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function clearProfileOptions()
     {
         $this->_profileOptions = array();
         return $this;
     }
 
+    /**
+     * Add a build profile dependency prefix
+     *
+     * If just the prefix is passed, sets path to "../$prefix".
+     * 
+     * @param  string $prefix 
+     * @param  null|string $path 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function addProfilePrefix($prefix, $path = null)
     {
         if (null === $path) {
@@ -199,6 +396,12 @@ class Zend_Dojo_BuildLayer
         return $this;
     }
 
+    /**
+     * Set multiple dependency prefixes for bulid profile
+     * 
+     * @param  array $prefixes 
+     * @return Zend_Dojo_BuildLayer
+     */
     public function setProfilePrefixes(array $prefixes)
     {
         foreach ($prefixes as $prefix => $path) {
@@ -207,6 +410,11 @@ class Zend_Dojo_BuildLayer
         return $this;
     }
 
+    /**
+     * Get build profile dependency prefixes
+     * 
+     * @return array
+     */
     public function getProfilePrefixes()
     {
         $layerName = $this->getLayerName();
@@ -232,6 +440,11 @@ class Zend_Dojo_BuildLayer
         return $this->_profilePrefixes;
     }
 
+    /**
+     * Generate module layer script
+     * 
+     * @return string
+     */
     public function generateLayerScript()
     {
         $helper        = $this->getDojoHelper();
@@ -267,6 +480,11 @@ class Zend_Dojo_BuildLayer
         return $content;
     }
 
+    /**
+     * Generate build profile
+     * 
+     * @return string
+     */
     public function generateBuildProfile()
     {
         $profileOptions  = $this->getProfileOptions();
@@ -289,12 +507,24 @@ class Zend_Dojo_BuildLayer
         return 'dependencies = ' . $this->_filterJsonProfileToJavascript($profile) . ';';
     }
 
+    /**
+     * Retrieve module prefix
+     * 
+     * @param  string $module 
+     * @return void
+     */
     protected function _getPrefix($module)
     {
         $segments  = explode('.', $module, 2);
         return $segments[0];
     }
 
+    /**
+     * Filter a JSON build profile to JavaScript
+     * 
+     * @param  string $profile 
+     * @return string
+     */
     protected function _filterJsonProfileToJavascript($profile)
     {
         require_once 'Zend/Json.php';

tests/Zend/Dojo/BuildLayerTest.php

@@ -97,20 +97,6 @@ class Zend_Dojo_BuildLayerTest extends PHPUnit_Framework_TestCase
         $this->assertEquals($path, $build->getLayerScriptPath());
     }
 
-    public function testProfilePathIsNullByDefault()
-    {
-        $build = new Zend_Dojo_BuildLayer();
-        $this->assertNull($build->getProfilePath());
-    }
-
-    public function testProfilePathShouldBeMutable()
-    {
-        $build = new Zend_Dojo_BuildLayer();
-        $path  = __FILE__;
-        $build->setProfilePath($path);
-        $this->assertEquals($path, $build->getProfilePath());
-    }
-
     public function testShouldNotConsumeJavascriptByDefault()
     {
         $build = new Zend_Dojo_BuildLayer();