Updated phpdoc documentation.

Remove unused function handleField from DashboardForm. Added field XMLSafeMessage to DashboardLogMessage. Renamed JS function startUpdate and stopUpdate to startUpdateCountdown and stopUpdateCountdown

code/AutomaticRefreshButton.php

@@ -1,4 +1,8 @@
 <?php
+/**
+ * A button that turns automatic refresh on and off. It also displays a
+ *  progress bar for the coutdown. Needs additional CSS and JS to work.
+ */
 class AutomaticRefreshButton extends FormAction {
 	public function __construct($action, $title = "", $form = null){
 		parent::__construct($action, $title, $form);

code/DashboardForm.php

@@ -1,4 +1,12 @@
 <?php
+/**
+ * The Form that is displayed in the Dashboard.
+ * 
+ * It takes care of forwarding submissions to the Panels' Controllers.
+ * 
+ * Currently, there is no special handling of sub fields. If this is required,
+ *  it is necessary to override handleField().
+ */
 class DashboardForm extends Form {
 
 	private $callbacks = array();
@@ -11,6 +19,10 @@ public function __construct($controller, $name, $fields, $actions, $validator =
 		}
 	}
 
+	/**
+	 * Add a panel to the Form. Each Panel will be diesplayed in a Tab.
+	 * @param DashboardPanel $panel
+	 */
 	public function addPanel(DashboardPanel $panel) {
 		//Get information from $panel and add it to our form
 		//@TODO: Preserve tab hierarchy.
@@ -29,6 +41,14 @@ public function addPanel(DashboardPanel $panel) {
 		}
 	}
 
+	/**
+	 * Check if the Form contains the FormField $fieldName in the Tab $panelName.
+	 * 
+	 * Used for testing.
+	 * @param string $panelName
+	 * @param string $fieldName
+	 * @return boolean
+	 */
 	public function findField($panelName, $fieldName) {
 		return $this->fields->fieldByName("Root.$panelName.$fieldName");
 	}
@@ -91,11 +111,4 @@ public function httpSubmission($request) {
 
 		return parent::httpSubmission($request);
 	}
-
-	public function handleField($request) {
-		echo $request->param('FieldName');
-		//TODO: intercept/redirect
-		return parent::handleField($request);
-	}
-
 }

code/DashboardLog.php

@@ -1,4 +1,18 @@
 <?php
+/**
+ * This is the factory class for log wrappers.
+ * 
+ * The recommended way of logging is:
+ *   1. Get a logWrapper by calling Log::get_log_wrapper.
+ *     We suggest using __class__ as the streamID:
+ *     $log_wrapper = Log::get_log_wrapper(__class__);
+ *   2. Check if the stream is enabled:
+ *     if($log_wrapper->is_enabled()) ...
+ *   3. Log your message
+ *	   $log_wrapper->log('Hello World');
+ * 
+ * If you are in a hurry, you can instead just call DashboardLog::log.
+ */
 require_once 'Zend/Log/Writer/Stream.php';
 class DashboardLog {
 	/** 
@@ -17,6 +31,7 @@ class DashboardLog {
 	/** @var Zend_Log_Writer_Stream The writer used to write to the log file. */
 	private static $log_file_writer = null;
 
+	/** @var array the log files that can be viewed. */
 	private static $available_log_files = array();
 
 
@@ -69,6 +84,16 @@ public static function log($message, $streamID = 'DEFAULT',
 		$wrapper->log($message, $priority);
 	}
 
+	/**
+	 * Register the logfile at $path under as $name. It can then be read
+	 *  by calling read_log_file(-1, $name).
+	 * 
+	 * The log file already has to exist at $path, when this function is called!
+	 * 
+	 * @param string $name
+	 * @param string $path
+	 * @throws InvalidArgumentException if there is no file at $path
+	 */
 	public static function register_log_file($name, $path){
 		if(!is_file($path)){
 			throw new InvalidArgumentException("Invalid path: $path");

code/DashboardLogController.php

@@ -1,10 +1,22 @@
 <?php
-class DashboardLogController extends Controller  implements DashboardPanelContentProvider {
+/**
+ * The Controller for the dashboard log pabel.
+ */
+class DashboardLogController extends Controller implements DashboardPanelContentProvider {
+	/**
+	 * Add the log panel to the Dashboard.
+	 */
 	public static function add_log_panel(){
 		$dlc = new DashboardLogController();
 		$dlc->addLogPanel();
 	}
 
+	/**
+	 * Get log data stored in the session.
+	 * If a parameter is supplied via the URL, only requests newer than that
+	 *  are returned.
+	 * @return ArrayList
+	 */
 	public function GetLoggedData(){
 		$param = $this->request->latestParam('ID');
 		$newerThan = $param === null ? 0 : $param;
@@ -14,7 +26,7 @@ public function GetLoggedData(){
 	/**
 	 * This is an action controller that returns the newest log messages.
 	 * It gets called via AJAX.
-	 * 
+	 * @return string the HTML.
 	 */
 	public function getlog($request = null){
 		if($request != null) {
@@ -23,6 +35,12 @@ public function getlog($request = null){
 		return $this->renderWith('DeveloperDashboardLogAjax');
 	}
 
+	/**
+	 * Get a button to control the display of the stream specified by the 
+	 *  URL parameter.
+	 * @param SS_HTTPRequest $request
+	 * @return string the HTML
+	 */
 	public function getstreambutton(SS_HTTPRequest $request = null){
 		if($request == null) return;
 		$ad = new ArrayData(array('Title'=>$request->latestParam('ID')));
@@ -58,6 +76,9 @@ public function getPanelContent(DashboardPanel $panel){
 		$panel->addFormField($logarea->performReadonlyTransformation());
 	}
 
+	/**
+	 * Does the work for adding the log panel to the Dashboard.
+	 */
 	private function addLogPanel(){
 		$panel = new DashboardPanel('Logs');
 		$panel->setContentProvider($this);

code/DashboardLogFilter.php

@@ -1,4 +1,7 @@
 <?php
+/**
+ * A filter used to enable and disable log streams.
+ */
 require_once 'Zend/Log/Filter/Interface.php';
 class DashboardLogFilter implements Zend_Log_Filter_Interface {
 	private $enabled = true;

code/DashboardLogMessage.php

@@ -1,8 +1,12 @@
 <?php
+/**
+ * Data object for a log message.
+ */
 class DashboardLogMessage extends ViewableData {
 	public $StreamID;
 	public $Timestamp;
 	public $Message;
+	public $XMLSafeMessage;
 
 	/**
 	 * Construct from a Zend_Log message.
@@ -11,17 +15,27 @@ class DashboardLogMessage extends ViewableData {
 	 */
 	public function __construct($event, $streamID){
 		$this->Message = $event['message'];
+		$this->XMLSafeMessage = isset($event['XMLSafe']) ? $event['XMLSafe'] : null;
 		$this->StreamID = $streamID;
 		$this->Timestamp = $event['timestamp'];
 	}
 
+	/**
+	 * Cast the object to a string.
+	 * @return string
+	 */
 	public function __toString(){
 		return "[{$this->StreamID}] {$this->Timestamp} {$this->Message}";
 	}
 
+	/**
+	 * Get an XML safe representation of this object.
+	 * @return string
+	 */
 	public function toXML(){
-		return (string)$this;
-		//return '<p class="">'.(string)$this.'</p>';
+		return "[{$this->StreamID}] {$this->Timestamp} "
+			.$this->XMLSafeMessage != null ? $this->XMLSafeMessage 
+				: Convert::raw2xml($this->Message);
 	}
 
 	/**

code/DashboardLogWrapper.php

@@ -1,10 +1,13 @@
 <?php
-require_once 'Zend/Log.php';
 /**
  * This class wraps Zend_Log. If you just want to log something call log().
  * For more advanced tasks (e.g. adding filters), you can directly access
  *  the underlying Zend_Log instance via $logger;
+ * The purpose of this wrapper is to attach a filter to the logger that allows
+ *   enabling or disabling the log stream. It also exposes the state of the
+ *   stream (enabled or disabled) via the is_enabled method.
  */
+require_once 'Zend/Log.php';
 class DashboardLogWrapper {
 	/** @var Zend_Log The instance that is wrapped. */
 	public $logger;
@@ -17,14 +20,29 @@ public function __construct(){
 		$this->logger->addFilter($this->filter);
 	}
 
+	/**
+	 * Check if the logger is enabled.
+	 * @return boolean
+	 */
 	public function is_enabled(){
 		return $this->filter->is_enabled();
 	}
 
+	/**
+	 * Enable or disable the logger.
+	 * @param boolean $enabled
+	 */
 	public function set_enabled($enabled){
 		$this->filter->set_enabled($enabled);
 	}
 
+	/**
+	 * Log a message to the logger.
+	 * @see Zend_Log
+	 * @param string $message
+	 * @param type $priority
+	 * @param type $extras
+	 */
 	public function log($message, $priority = Zend_Log::INFO, $extras=null){
 		if(is_object($message) || is_array($message)){
 			$message = '<pre>'.print_r($message,1).'</pre>';

code/DashboardLogWriter.php

@@ -56,6 +56,14 @@ private function __construct($streamID) {
 		$this->storage = DashboardSessionStorage::inst();
 	}
 
+	/**
+     * Write a message to the log. If the message contains HTML/XML,
+	 *  the caller is responsible for setting $event['XMLSafe']
+	 *  to an XML safe representation.
+	 * 
+	 * @see Zend_Log_Writer_Abstract
+	 * @param type $event
+	 */
 	public function _write($event) {
 		/*
 		 * TODO We currently throw away all additional information

code/DashboardPanel.php

@@ -69,9 +69,10 @@ public function getName(){
 	/**
 	 * Allows to update the panel's content before it is displayed.
 	 * 
-	 * The method getPanelContent is called on $provider before the form is displayed.
-	 * This can be used to add content that was not available when this panel 
-	 *  was constructed, such as data from the session or the database.
+	 * The method getPanelContent is called on $provider before the form is
+	 *  displayed. This can be used to add content that was not available when
+	 *  this panel was constructed, such as data from the session or the
+	 *  database.
 	 * @param DashboardPanelContentProvider $provider
 	 */
 	public function setContentProvider(DashboardPanelContentProvider $provider) {
@@ -119,7 +120,8 @@ public function updateContent(){
 	 * @param FormField $formField
 	 * @param Controller $controller
 	 * @param string $methodName
-	 * @throws InvalidArgumentException if a controller is set, but no callback method can be found.
+	 * @throws InvalidArgumentException if a controller is set, but no callback
+	 *  method can be found.
 	 */
 	public function addFormField(FormField $formField,
 		Controller $controller = null, $methodName = null
@@ -156,6 +158,8 @@ public function addFormField(FormField $formField,
 	 * 
 	 * This allows to forward the action $action from the DeveloperDashboard to
 	 *  a different controller.
+	 * If $action already exists in the DeveloperDashboard, it will be
+	 *  overwritten.
 	 * 
 	 * @param string $action the name of the action
 	 * @param Controller $controller

code/DashboardPanelContentProvider.php

@@ -1,4 +1,15 @@
 <?php
+/**
+ * Interface to provide a function to update the panel content.
+ */
 interface DashboardPanelContentProvider {
+	/**
+	 * An update callback function that is called before the dashboard
+	 *  is displayed. The panel $panel will be overwritten by the return value
+	 *  of this function. This function can be used just like getCMSFields().
+	 * 
+	 * @param DashboardPanel $panel
+	 * @return DashboardPanel
+	 */
 	public function getPanelContent(DashboardPanel $panel);
 }

code/DashboardSessionStorage.php

@@ -1,8 +1,11 @@
 <?php
 /**
- * Singleton class.
+ * Store settings and log messages in the session.
+ * 
+ * Singleton class
  */
 class DashboardSessionStorage {
+	/** @var DashboardSessionStorage the singleton instance. */
 	private static $instance = null;
 	/** @var int Number of requests that are stored in the session */
 	public static $requests_to_keep = 10;
@@ -13,8 +16,12 @@ class DashboardSessionStorage {
 	 * This is an entry in the array $_SESSION[$session_key].
 	 */
 	private static $log_message_key = 'LOG_MESSAGES';
-
+	/** @var array the data that is stored in the session */
 	private $sessionData = array();
+	/** 
+	 * @var int the number of the current request. 
+	 * Requests that do not generate log data are not counted.
+	 */
 	private $requestNumber = -1;
 
 
@@ -60,11 +67,22 @@ public static function inst(){
 		return self::$instance;
 	}
 
+	/**
+	 * Store $value under the key $name.
+	 * @param type $name
+	 * @param type $value
+	 */
 	public function storeSetting($name, $value){
 		$this->sessionData[$name] = $value;
 		$this->updateSession();
 	}
 
+	/**
+	 * Load a previously stored value. If nothing was stored under $name, 
+	 *  false is returned.
+	 * @param string $name
+	 * @return mixed
+	 */
 	public function loadSetting($name){
 		if(!isset($this->sessionData[$name])){
 			return false;
@@ -73,7 +91,11 @@ public function loadSetting($name){
 		}		
 	}
 
-	public function storeMessageObject($messageObj) {
+	/**
+	 * Store a DashboardLogMessage object in the session.
+	 * @param DashboardLogMessage $messageObj
+	 */
+	public function storeMessageObject(DashboardLogMessage $messageObj) {
 		if(!isset($this->sessionData[self::$log_message_key][$this->requestNumber])){
 			//Append new array for messages written by this request.
 			$this->sessionData[self::$log_message_key][$this->requestNumber] = array(
@@ -132,6 +154,10 @@ public function getMessagesFromSession($newerThan = 0) {
 		return $requests;
 	}
 
+	/**
+	 * Update the session. Call this method after every change to the data, 
+	 *  to make sure that the session stores the most recent values.
+	 */
 	private function updateSession(){
 		Session::set(self::$session_key, $this->sessionData);
 		Session::save();