Index: /trunk/include/block.class.php
===================================================================
--- /trunk/include/block.class.php	(revision 25761)
+++ /trunk/include/block.class.php	(revision 25762)
@@ -20,21 +20,40 @@
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package functions\menubar
+ */
+
+
+/**
+ * Manages a set of RegisteredBlock and DisplayBlock.
+ */
 class BlockManager
 {
+  /** @var string */
   protected $id;
-  protected $registered_blocks=array();
+  /** @var RegisteredBlock[] */
+  protected $registered_blocks = array();
+  /** @var DisplayBlock[] */
   protected $display_blocks = array();
 
-  public function BlockManager($id)
+  /**
+   * @param string $id
+   */
+  public function __construct($id)
   {
     $this->id = $id;
   }
 
-  /** triggers an action that allows implementors of menu blocks to register the blocks*/
+  /**
+   * Triggers a notice that allows plugins of menu blocks to register the blocks.
+   */
   public function load_registered_blocks()
   {
-    trigger_action('blockmanager_register_blocks', array(&$this) );
-  }
-
+    trigger_action('blockmanager_register_blocks', array(&$this));
+  }
+  
+  /**
+   * @return string
+   */
   public function get_id()
   {
@@ -42,4 +61,7 @@
   }
 
+  /**
+   * @return RegisteredBlock[]
+   */
   public function get_registered_blocks()
   {
@@ -47,10 +69,12 @@
   }
 
-  /** registers a block with this menu. usually called as a result of menubar_register_blocks action
-   * @param MenuBlock block
-  */
+  /**
+   * Add a block with the menu. Usually called in 'blockmanager_register_blocks' event.
+   *
+   * @param RegisteredBlock &$block
+   */
   public function register_block(&$block)
   {
-    if ( isset($this->registered_blocks[$block->get_id()] ) )
+    if (isset($this->registered_blocks[$block->get_id()]))
     {
       trigger_error("Block '".$block->get_id()."' is already registered", E_USER_WARNING);
@@ -61,8 +85,9 @@
   }
 
-  /** performs one time preparation of registered blocks for display;
-   * triggers the action menubar_prepare_display where implementors can
+  /**
+   * Performs one time preparation of registered blocks for display.
+   * Triggers 'blockmanager_prepare_display' event where plugins can
    * reposition or hide blocks
-  */
+   */
   public function prepare_display()
   {
@@ -70,12 +95,14 @@
     $conf_id = 'blk_'.$this->id;
     $mb_conf = isset($conf[$conf_id]) ? $conf[$conf_id] : array();
-    if ( !is_array($mb_conf) )
+    if (!is_array($mb_conf))
+    {
       $mb_conf = @unserialize($mb_conf);
+    }
 
     $idx = 1;
-    foreach( $this->registered_blocks as $id => $block )
-    {
-      $pos = isset( $mb_conf[$id] ) ? $mb_conf[$id] : $idx*50;
-      if ( $pos>0 )
+    foreach ($this->registered_blocks as $id => $block)
+    {
+      $pos = isset($mb_conf[$id]) ? $mb_conf[$id] : $idx*50;
+      if ($pos>0)
       {
         $this->display_blocks[$id] = new DisplayBlock($block);
@@ -85,25 +112,39 @@
     }
     $this->sort_blocks();
-    trigger_action( 'blockmanager_prepare_display', array(&$this) );
+    trigger_action('blockmanager_prepare_display', array(&$this));
     $this->sort_blocks();
   }
 
-  /** returns true if the block whose id is hidden
-   * @param string block_id
-  */
+  /**
+   * Returns true if the block is hidden.
+   *
+   * @param string $block_id
+   * @return bool
+   */
   public function is_hidden($block_id)
   {
-    return isset($this->display_blocks[$block_id]) ? false : true;
-  }
-
+    return !isset($this->display_blocks[$block_id]);
+  }
+
+  /**
+   * Remove a block from the displayed blocks.
+   *
+   * @param string $block_id
+   */
   public function hide_block($block_id)
   {
-    unset( $this->display_blocks[$block_id] );
-  }
-
+    unset($this->display_blocks[$block_id]);
+  }
+
+  /**
+   * Returns a visible block.
+   *
+   * @param string $block_id
+   * @return &DisplayBlock|null
+   */
   public function &get_block($block_id)
   {
     $tmp = null;
-    if ( isset($this->display_blocks[$block_id]) )
+    if (isset($this->display_blocks[$block_id]))
     {
       return $this->display_blocks[$block_id];
@@ -112,7 +153,13 @@
   }
 
+  /**
+   * Changes the position of a block.
+   *
+   * @param string $block_id
+   * @param int $position
+   */
   public function set_block_position($block_id, $position)
   {
-    if ( isset($this->display_blocks[$block_id]) )
+    if (isset($this->display_blocks[$block_id]))
     {
       $this->display_blocks[$block_id]->set_position($position);
@@ -120,9 +167,15 @@
   }
 
+  /**
+   * Sorts the blocks.
+   */
   protected function sort_blocks()
   {
-    uasort( $this->display_blocks, array('BlockManager', 'cmp_by_position') );
-  }
-
+    uasort($this->display_blocks, array('BlockManager', 'cmp_by_position'));
+  }
+
+  /**
+   * Callback for blocks sorting.
+   */
   static protected function cmp_by_position($a, $b)
   {
@@ -130,4 +183,10 @@
   }
 
+  /**
+   * Parse the menu and assign the result in a template variable.
+   *
+   * @param string $var
+   * @param string $file
+   */
   public function apply($var, $file)
   {
@@ -137,7 +196,7 @@
     trigger_action('blockmanager_apply', array(&$this) );
 
-    foreach( $this->display_blocks as $id=>$block)
-    {
-      if (empty($block->raw_content) and empty($block->template) )
+    foreach ($this->display_blocks as $id=>$block)
+    {
+      if (empty($block->raw_content) and empty($block->template))
       {
         $this->hide_block($id);
@@ -150,14 +209,23 @@
 }
 
+
 /**
- * Represents a menu block registered in a Menu object.
+ * Represents a menu block registered in a BlockManager object.
  */
 class RegisteredBlock
 {
+  /** @var string */
   protected $id;
+  /** @var string */
   protected $name;
+  /** @var string */
   protected $owner;
 
-  public function RegisteredBlock($id, $name, $owner)
+  /**
+   * @param string $id
+   * @param string $name
+   * @param string $owner
+   */
+  public function __construct($id, $name, $owner)
   {
     $this->id = $id;
@@ -166,31 +234,76 @@
   }
 
-  public function get_id() { return $this->id; }
-  public function get_name() { return $this->name; }
-  public function get_owner() { return $this->owner; }
+  /**
+   * @return string
+   */
+  public function get_id()
+  {
+    return $this->id;
+  }
+
+  /**
+   * @return string
+   */
+  public function get_name()
+  {
+    return $this->name;
+  }
+
+  /**
+   * @return string
+   */
+  public function get_owner()
+  {
+    return $this->owner;
+  }
 }
 
+
 /**
- * Represents a menu block ready for display in the Menu object.
+ * Represents a menu block ready for display in the BlockManager object.
  */
 class DisplayBlock
 {
+  /** @var RegisteredBlock */
   protected $_registeredBlock;
+  /** @var int */
   protected $_position;
-
+  /** @var string */
   protected $_title;
 
+  /** @var mixed */
   public $data;
+  /** @var string */
   public $template;
+  /** @var string */
   public $raw_content;
 
-  public function DisplayBlock($registeredBlock)
-  {
-    $this->_registeredBlock = &$registeredBlock;
-  }
-
-  public function &get_block() { return $this->_registeredBlock; }
-
-  public function get_position() { return $this->_position; }
+  /**
+   * @param RegisteredBlock &$block
+   */
+  public function __construct($block)
+  {
+    $this->_registeredBlock = &$block;
+  }
+
+  /**
+   * @return &RegisteredBlock
+   */
+  public function &get_block()
+  {
+    return $this->_registeredBlock;
+  }
+
+  /**
+   * @return int
+   */
+  public function get_position()
+  {
+    return $this->_position;
+  }
+
+  /**
+   * @param int $position
+   */
   public function set_position($position)
   {
@@ -198,12 +311,22 @@
   }
 
+  /**
+   * @return string
+   */
   public function get_title()
   {
     if (isset($this->_title))
+    {
       return $this->_title;
+    }
     else
+    {
       return $this->_registeredBlock->get_name();
-  }
-
+    }
+  }
+
+  /**
+   * @param string
+   */
   public function set_title($title)
   {
Index: /trunk/include/menubar.inc.php
===================================================================
--- /trunk/include/menubar.inc.php	(revision 25761)
+++ /trunk/include/menubar.inc.php	(revision 25762)
@@ -23,6 +23,5 @@
 
 /**
- * This file is included by the main page to show the menu bar
- *
+ * @package functions\menubar
  */
 
@@ -31,4 +30,7 @@
 initialize_menu();
 
+/**
+ * Setups each block the main menubar.
+ */ 
 function initialize_menu()
 {
@@ -330,3 +332,4 @@
   $menu->apply('MENUBAR',  'menubar.tpl' );
 }
+
 ?>
