Adds proper documentation and explains some of the navigation/menu usage behavior via the BaseUI example menus

Templates/BaseGame/game/data/UI/scripts/menuNavigation.tscript

@@ -1,3 +1,12 @@
+//==============================================================================
+/// Summary:
+/// This function sets the root page for the navigation stack. The root page is 'below'
+/// all other normal pages and cannot be popped like a normal page.
+/// When we set a new root page, we first check if we have an existing root page.
+/// If we do, we run the usual canClose() then onClose() function pair, then we 
+/// set it and call the onOpen() for the new root page.
+/// 
+/// \param %rootPage (guiControl) The new guiControl that is being set as the root page of the navigation stack
 function UINavigation::setRootPage(%this, %rootPage)
 {
    if(!isObject(%this.pageStack))
@@ -36,6 +45,25 @@ function UINavigation::setRootPage(%this, %rootPage)
       %rootPage.call("onOpen");
 }
 
+//==============================================================================
+/// Summary:
+/// This function pushes a page onto the given UINavigation-classed GUIContainer's stack
+/// The order of operations is thus:
+/// 1) check to see if the new page being pushed says it can open via the canOpen() function. 
+///    If this method is not defined, it defaults to true, as there's no impediment to continuing
+///    If this check returns false, the pushPage event cancels.
+/// 2) check to see if the current page on the stack says it can close. Similar to 
+///    the canOpen() check on the new page, we default to true
+///    If this check returns false, the pushPage event cancels.
+/// 3) Call - if defined - onClose() on the current top page of the stack
+/// 4) Add the new page onto the stack
+/// 5) Call - if defined - onOpen() on the new page
+/// 6) Finally, if we defined a callback, call that.
+/// With this all run, the previous top page has done any cleanup work it needed to
+/// and the new top page has been opened successfully.
+/// 
+/// \param %newPage (guiControl) The new guiControl that is being added onto the page stack
+/// \param %callback[optional]: (Evaluable string) A evalable statement to invoke when the push has been completed
 function UINavigation::pushPage(%this, %newPage, %callback)
 {
    if(!isObject(%this.pageStack))
@@ -80,6 +108,24 @@ function UINavigation::pushPage(%this, %newPage, %callback)
    eval(%callback);
 }
 
+//==============================================================================
+/// Summary:
+/// This function pops the topmost page off the given UINavigation-classed GUIContainer's stack
+/// The order of operations is thus:
+/// 1) check to see if the top page being popped says it can close via the canClose() function. 
+///    If this method is not defined, it defaults to true, as there's no impediment to continuing
+///    If this check returns false, the popPage event cancels.
+/// 2) check to see if the previous page on the stack says it can open. Similar to 
+///    the canClose() check on the new page, we default to true
+///    If this check returns false, the popPage event cancels.
+/// 3) Call - if defined - onClose() on the current top page of the stack
+/// 4) Remove the top page
+/// 5) Call - if defined - onOpen() on the now topmost page
+/// 6) Finally, if we defined a callback, call that.
+/// With this all run, the previous top page has done any cleanup work it needed to
+/// and the new top page has been opened successfully.
+/// 
+/// \param %callback[optional] (Evaluable string) A evalable statement to invoke when the pop has been completed
 function UINavigation::popPage(%this, %callback)
 {
    if(%this.pageStack.count() == 0)
@@ -128,6 +174,12 @@ function UINavigation::popPage(%this, %callback)
    eval(%callback);
 }
 
+//==============================================================================
+/// Summary:
+/// In order tops the topmost page in a loop until it has closed the entire stack,
+/// leaving only the root page
+/// 
+/// \param %callback[optional] (Evaluable String) A evalable statement to invoke when the pop has been completed
 function UINavigation::popToRoot(%this, %callback)
 {
    %pageChanged = false;
@@ -177,6 +229,10 @@ function UINavigation::popToRoot(%this, %callback)
       eval(%callback);
 }
 
+//==============================================================================
+/// Summary:
+/// Gets the current, topmost page on the stack. If no non-root pages are on the stack
+/// the root page is returned
 function UINavigation::getCurrentPage(%this)
 {
    if(isObject(%this.pageStack) && %this.pageStack.count() != 0)
@@ -192,6 +248,10 @@ function UINavigation::getCurrentPage(%this)
    return 0;
 }
 
+//==============================================================================
+/// Summary:
+/// Gets the page just under the topmost page in the stack. If there is no previous page
+/// then the root page is returned
 function UINavigation::getPreviousPage(%this)
 {
    if(isObject(%this.pageStack) && %this.pageStack.count() > 1)
@@ -207,6 +267,9 @@ function UINavigation::getPreviousPage(%this)
    return 0;
 }   
 
+//==============================================================================
+/// Summary:
+/// Gets the number of pages on the stack.
 function UINavigation::getPageCount(%this)
 {
    %count = 0;