MDL-30976 - navigation - Updating the api block documentation.

blocks/navigation/block_navigation.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -19,8 +18,8 @@
  * This file contains classes used to manage the navigation structures in Moodle
  * and was introduced as part of the changes occuring in Moodle 2.0
  *
- * @since 2.0
- * @package blocks
+ * @since     2.0
+ * @package   block_navigation
  * @copyright 2009 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -30,19 +29,20 @@
  *
  * Used to produce the global navigation block new to Moodle 2.0
  *
- * @package blocks
+ * @package   block_navigation
+ * @category  navigation
  * @copyright 2009 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class block_navigation extends block_base {
 
-    /** @var int */
+    /** @var int This allows for multiple navigation trees */
     public static $navcount;
-    /** @var string */
+    /** @var string The name of the block */
     public $blockname = null;
-    /** @var bool */
+    /** @var bool A switch to indicate whether content has been generated or not. */
     protected $contentgenerated = false;
-    /** @var bool|null */
+    /** @var bool|null variable for checking if the block is docked*/
     protected $docked = null;
 
     /** @var int Trim characters from the right */
@@ -63,7 +63,7 @@ function init() {
 
     /**
      * All multiple instances of this block
-     * @return bool Returns true
+     * @return bool Returns false
      */
     function instance_allow_multiple() {
         return false;
@@ -95,10 +95,18 @@ function  instance_can_be_hidden() {
         return false;
     }
 
+    /**
+     * Find out if an instance can be docked.
+     *
+     * @return bool true or false depending on whether the instance can be docked or not.
+     */
     function instance_can_be_docked() {
         return (parent::instance_can_be_docked() && (empty($this->config->enabledock) || $this->config->enabledock=='yes'));
     }
 
+    /**
+     * Gets Javascript that may be required for navigation
+     */
     function get_required_javascript() {
         global $CFG;
         user_preference_allow_ajax_update('docked_block_instance_'.$this->instance->id, PARAM_INT);
@@ -124,6 +132,8 @@ function get_required_javascript() {
 
     /**
      * Gets the content for this block by grabbing it from $this->page
+     *
+     * @return object $this->content
      */
     function get_content() {
         global $CFG, $OUTPUT;
@@ -134,7 +144,7 @@ function get_content() {
         // JS for navigation moved to the standard theme, the code will probably have to depend on the actual page structure
         // $this->page->requires->js('/lib/javascript-navigation.js');
         // Navcount is used to allow us to have multiple trees although I dont' know why
-        // you would want to trees the same
+        // you would want two trees the same
 
         block_navigation::$navcount++;
 
@@ -209,9 +219,9 @@ function get_content() {
      *
      * This function returns an array of HTML attributes for this block including
      * the defaults
-     * {@link block_tree->html_attributes()} is used to get the default arguments
+     * {@see block_tree::html_attributes()} is used to get the default arguments
      * and then we check whether the user has enabled hover expansion and add the
-     * appropriate hover class if it has
+     * appropriate hover class if it has.
      *
      * @return array An array of HTML attributes
      */
@@ -227,6 +237,7 @@ public function html_attributes() {
      * Trims the text and shorttext properties of this node and optionally
      * all of its children.
      *
+     * @param navigation_node $node
      * @param int $mode One of navigation_node::TRIM_*
      * @param int $long The length to trim text to
      * @param int $short The length to trim shorttext to

blocks/navigation/edit_form.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -18,16 +17,17 @@
 /**
  * Form for editing global navigation instances.
  *
- * @since 2.0
- * @package blocks
+ * @since     2.0
+ * @package   block_navigation
  * @copyright 2009 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 /**
  * Form for editing global navigation instances.
  *
- * @package blocks
+ * @package   block_navigation
+ * @category  navigation
  * @copyright 2009 Sam Hemelryk
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */

blocks/navigation/renderer.php

@@ -1,7 +1,45 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Outputs the navigation tree.
+ *
+ * @since     2.0
+ * @package   block_navigation
+ * @copyright 2009 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+/**
+ * Renderer for block navigation
+ *
+ * @package   block_navigation
+ * @category  navigation
+ * @copyright 2009 Sam Hemelryk
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class block_navigation_renderer extends plugin_renderer_base {
-
+    /**
+     * Returns the content of the navigation tree.
+     *
+     * @param global_navigation $navigation
+     * @param int $expansionlimit
+     * @param array $options
+     * @return string $content
+     */
     public function navigation_tree(global_navigation $navigation, $expansionlimit, array $options = array()) {
         $navigation->add_class('navigation_node');
         $content = $this->navigation_node(array($navigation), array('class'=>'block_tree list'), $expansionlimit, $options);
@@ -10,7 +48,16 @@ public function navigation_tree(global_navigation $navigation, $expansionlimit,
         }
         return $content;
     }
-
+    /**
+     * Produces a navigation node for the navigation tree
+     *
+     * @param array $items
+     * @param array $attrs
+     * @param int $expansionlimit
+     * @param array $options
+     * @param int $depth
+     * @return string
+     */
     protected function navigation_node($items, $attrs=array(), $expansionlimit=null, array $options = array(), $depth=1) {
 
         // exit if empty, we don't want an empty ul element

blocks/navigation/version.php

@@ -17,8 +17,7 @@
 /**
  * Version details
  *
- * @package    block
- * @subpackage navigation
+ * @package    block_navigation
  * @copyright  1999 onwards Martin Dougiamas (http://dougiamas.com)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */