From deaf04c7b7e30d6f115ee2b91c98304d0fa3946c Mon Sep 17 00:00:00 2001
From: Sam Hemelryk <sam@moodle.com>
Date: Thu, 5 Aug 2010 02:44:03 +0000
Subject: [PATCH] NOBUG updating PHP docs for lib/navigationlib.php

---
 lib/navigationlib.php | 72 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 69 insertions(+), 3 deletions(-)

diff --git a/lib/navigationlib.php b/lib/navigationlib.php
index e0721463f35..446a1bdc03a 100644
--- a/lib/navigationlib.php
+++ b/lib/navigationlib.php
@@ -1665,7 +1665,7 @@ class global_navigation extends navigation_node {
                             //stop when the first visible plugin is found
                             $gradeavailable = true;
                             break;
-        }
+                        }
                     }
                 }
 
@@ -1911,7 +1911,17 @@ class global_navigation extends navigation_node {
         }
         return true;
     }
-
+    /**
+     * This generates the the structure of the course that won't be generated when
+     * the modules and sections are added.
+     *
+     * Things such as the reports branch, the participants branch, blogs... get
+     * added to the course node by this method.
+     *
+     * @param navigation_node $coursenode
+     * @param stdClass $course
+     * @return bool True for successfull generation
+     */
     public function add_front_page_course_essentials(navigation_node $coursenode, stdClass $course) {
         global $CFG;
 
@@ -1979,6 +1989,19 @@ class global_navigation extends navigation_node {
         $this->cache->clear();
     }
 
+    /**
+     * Sets an expansion limit for the navigation
+     *
+     * The expansion limit is used to prevent the display of content that has a type
+     * greater than the provided $type.
+     *
+     * Can be used to ensure things such as activities or activity content don't get
+     * shown on the navigation.
+     * They are still generated in order to ensure the navbar still makes sense.
+     *
+     * @param int $type One of navigation_node::TYPE_*
+     * @return <type>
+     */
     public function set_expansion_limit($type) {
         $nodes = $this->find_all_of_type($type);
         foreach ($nodes as &$node) {
@@ -1997,7 +2020,21 @@ class global_navigation extends navigation_node {
         }
         return true;
     }
-
+    /**
+     * Attempts to get the navigation with the given key from this nodes children.
+     *
+     * This function only looks at this nodes children, it does NOT look recursivily.
+     * If the node can't be found then false is returned.
+     *
+     * If you need to search recursivily then use the {@see find()} method.
+     *
+     * Note: If you are trying to set the active node {@see navigation_node::override_active_url()}
+     * may be of more use to you.
+     *
+     * @param string|int $key The key of the node you wish to receive.
+     * @param int $type One of navigation_node::TYPE_*
+     * @return navigation_node|false
+     */
     public function get($key, $type = null) {
         if (!$this->initialised) {
             $this->initialise();
@@ -2005,6 +2042,23 @@ class global_navigation extends navigation_node {
         return parent::get($key, $type);
     }
 
+    /**
+     * Searches this nodes children and thier children to find a navigation node
+     * with the matching key and type.
+     *
+     * This method is recursive and searches children so until either a node is
+     * found of there are no more nodes to search.
+     *
+     * If you know that the node being searched for is a child of this node
+     * then use the {@see get()} method instead.
+     *
+     * Note: If you are trying to set the active node {@see navigation_node::override_active_url()}
+     * may be of more use to you.
+     *
+     * @param string|int $key The key of the node you wish to receive.
+     * @param int $type One of navigation_node::TYPE_*
+     * @return navigation_node|false
+     */
     public function find($key, $type) {
         if (!$this->initialised) {
             $this->initialise();
@@ -2134,6 +2188,10 @@ class global_navigation_for_ajax extends global_navigation {
         return $this->expandable;
     }
 
+    /**
+     * Returns an array of expandable nodes
+     * @return array
+     */
     public function get_expandable() {
         return $this->expandable;
     }
@@ -3075,6 +3133,14 @@ class settings_navigation extends navigation_node {
         return $usernode;
     }
 
+    /**
+     * Extends the settings navigation for the given user.
+     *
+     * Note: This method gets called automatically if you call
+     * $PAGE->navigation->extend_for_user($userid)
+     *
+     * @param int $userid
+     */
     public function extend_for_user($userid) {
         global $CFG;