Documented 21 functions across 6 files

Docs/TestDoc/docs/html/clipboard.js

@@ -50,6 +50,10 @@ $(function() {
         navigator.clipboard.writeText(text);
         this.classList.add("success")
         this.innerHTML = clipboard_successIcon
+        /**
+         * @description Removes the "success" class from an element and replaces its innerHTML
+         * with a clipart icon of a computer file.
+         */
         window.setTimeout(() => { // switch back to normal icon after timeout
             this.classList.remove("success")
             this.innerHTML = clipboard_icon

Docs/TestDoc/docs/html/cookie.js

@@ -6,6 +6,19 @@
 let Cookie = {
   cookie_namespace: 'doxygen_',
 
+  /**
+   * @description Retrieves a setting value from either local storage or the document
+   * cookie, and returns it if found, or a default value otherwise.
+   * 
+   * @param { string } cookie - name of the cookie to be looked up in local or session
+   * storage.
+   * 
+   * @param { string } defVal - default value returned if the function fails to find
+   * the cookie value in the storage.
+   * 
+   * @returns { string } the value of a cookie setting, or the default value if the
+   * cookie is not found.
+   */
   readSetting(cookie,defVal) {
     if (window.chrome) {
       const val = localStorage.getItem(this.cookie_namespace+cookie) ||
@@ -28,6 +41,19 @@ let Cookie = {
     return defVal;
   },
 
+  /**
+   * @description Sets a cookie with a given name, value, and expiration time. It stores
+   * the cookie in either session storage or local storage, depending on the value of
+   * `days`.
+   * 
+   * @param { string } cookie - name of the cookie being set or updated in the documentation.
+   * 
+   * @param { string } val - value to be stored in the cookie.
+   * 
+   * @param { binary_expression } days - number of days that the cookie should be stored
+   * for, with values of 0 indicating a session cookie, -1 meaning deletion, and any
+   * other value specifying a specific storage time in milliseconds.
+   */
   writeSetting(cookie,val,days=10*365) { // default days='forever', 0=session cookie, -1=delete
     if (window.chrome) {
       if (days==0) {
@@ -44,6 +70,12 @@ let Cookie = {
     }
   },
 
+  /**
+   * @description Removes a setting from local or session storage based on the namespace
+   * and cookie provided.
+   * 
+   * @param { string } cookie - cookie to be erased from local or session storage.
+   */
   eraseSetting(cookie) {
     if (window.chrome) {
       if (localStorage.getItem(this.cookie_namespace+cookie)) {

Docs/TestDoc/docs/html/menu.js

@@ -22,7 +22,42 @@
 
  @licend  The above is the entire license notice for the JavaScript code in this file
  */
+/**
+ * @description Adds a search bar to the top navigation menu and sets up a checkbox
+ * for hiding the main menu when the search bar is opened.
+ * 
+ * @param { string } relPath - current URL path of the menu and is used to construct
+ * the search URL for searching submenus within the menu.
+ * 
+ * @param { boolean } searchEnabled - enablement of the search functionality within
+ * the menu.
+ * 
+ * @param { boolean } serverSide - server-side processing capability for search
+ * functionality, which affects the implementation of the search box and its associated
+ * events.
+ * 
+ * @param { string } searchPage - page to which the search functionality should be
+ * linked when the search box is clicked.
+ * 
+ * @param { string } search - search term that users will enter into a search box
+ * displayed within the main navigation menu.
+ * 
+ * @returns { string } HTML code that adds a search menu to a website's main navigation.
+ */
 function initMenu(relPath,searchEnabled,serverSide,searchPage,search) {
+  /**
+   * @description Generates an HTML tree structure based on JSON data provided, by
+   * recursively building a list of child nodes and their parent.
+   * 
+   * @param { object } data - tree structure that will be converted into an unordered
+   * list.
+   * 
+   * @param { string } relPath - current directory path relative to the root of the web
+   * application, and it is used to construct the full URLs for the children nodes in
+   * the tree.
+   * 
+   * @returns { string } a hierarchical HTML list of nodes and their subtree.
+   */
   function makeTree(data,relPath) {
     let result='';
     if ('children' in data) {

Docs/TestDoc/docs/html/navtree.js

@@ -23,6 +23,21 @@
  @licend  The above is the entire license notice for the JavaScript code in this file
  */
 
+/**
+ * @description 1) parses a markdown file to build a navigation tree, 2) sets up event
+ * listeners for hashchange and TOC links, and 3) initializes the main layout of the
+ * navigation tree.
+ * 
+ * @param { string } toroot - 0-based index of the root node in the Nav Tree structure,
+ * which is used to determine the appropriate breadcrumbs and children data for the
+ * current page.
+ * 
+ * @param { string } relpath - path to the current page relative to the root directory,
+ * and it is used to determine the appropriate child node to expand when clicking on
+ * a navigation link.
+ * 
+ * @returns { object } a navigable tree of HTML links to pages and subpages.
+ */
 function initNavTree(toroot,relpath) {
   let navTreeSubIndices = [];
   const ARROW_DOWN = '▼';

Docs/TestDoc/docs/html/resize.js

@@ -23,10 +23,20 @@
  @licend  The above is the entire license notice for the JavaScript code in this file
  */
 
+/**
+ * @description Sets up a resizable side nav and content area, and handles cookie-based
+ * width restoration, window resize events, drag and drop behaviors, and click events
+ * on the split bar and handle for collapsing the side nav.
+ */
 function initResizable() {
   let sidenav,navtree,content,header,footer,barWidth=6;
   const RESIZE_COOKIE_NAME = ''+'width';
 
+  /**
+   * @description Updates the margins of content and footer elements based on the width
+   * of a sidenav element, stores the difference between the sidenav width and the bar
+   * width in a cookie for future use.
+   */
   function resizeWidth() {
     const sidenavWidth = $(sidenav).outerWidth();
     content.css({marginLeft:parseInt(sidenavWidth)+"px"});
@@ -36,6 +46,14 @@ function initResizable() {
     Cookie.writeSetting(RESIZE_COOKIE_NAME,sidenavWidth-barWidth);
   }
 
+  /**
+   * @description Adjusts the CSS margins and width of content, footer, and side nav
+   * based on the value of `navWidth`.
+   * 
+   * @param { integer } navWidth - width of the side navigation element and is used to
+   * set the margins of the content, footer, and side navigation element in the CSS
+   * style properties applied by the function.
+   */
   function restoreWidth(navWidth) {
     content.css({marginLeft:parseInt(navWidth)+barWidth+"px"});
     if (typeof page_layout!=='undefined' && page_layout==1) {
@@ -44,6 +62,10 @@ function initResizable() {
     sidenav.css({width:navWidth + "px"});
   }
 
+  /**
+   * @description Adjusts the heights of various elements on a web page based on the
+   * window height and layout configuration.
+   */
   function resizeHeight() {
     const headerHeight = header.outerHeight();
     const footerHeight = footer.outerHeight();
@@ -66,6 +88,10 @@ function initResizable() {
     }
   }
 
+  /**
+   * @description Adjusts the width of a side nav based on the window width and stores
+   * the new width as a cookie for future reference.
+   */
   function collapseExpand() {
     let newWidth;
     if (sidenav.width()>0) {

Docs/TestDoc/docs/html/search/search.js

@@ -33,10 +33,63 @@ const searchResults = new SearchResults();
           storing this instance.  Is needed to be able to set timeouts.
    resultPath - path to use for external files
 */
+/**
+ * @description Manages the search panel's state, including hiding or showing the
+ * results window, resetting search field value, and activating or deactivating the
+ * search box based on its display style.
+ * 
+ * @param { object } name - name of the form element that triggered the `searchFunction`
+ * function, and it is used to identify the source of the search query and process
+ * its results accordingly.
+ * 
+ * @param { string } resultsPath - path where the search results are stored, and it
+ * is used to load the search results from the corresponding file when a search query
+ * is entered, by calling the `createResults` function with the correct path.
+ * 
+ * @param { string } extension - extension of the search query, and it is used to
+ * filter the search results by changing the query based on the inputted extension.
+ * 
+ * @returns { undefined` because no return statement has been defined } a JavaScript
+ * function that performs a search and displays the results in a popup window.
+ * 
+ * 		- `searchIndex`: The index of the currently selected search result.
+ * 		- `resultsPath`: A path to the directory containing the search results files.
+ * 		- `searchValue`: The value of the search field, used for searching the database.
+ * 		- `searchResults`: An instance of the `SearchResults` class, which represents
+ * the search results.
+ * 		- `lastSearchValue`: The last value entered in the search field.
+ * 		- `lastResultsPage`: The page number of the last searched results page.
+ * 		- `DOMSearchBox`: A reference to the search box HTML element.
+ * 		- `DOMPopupSearchResultsWindow`: A reference to the popup window containing the
+ * search results.
+ * 		- `DOMSearchClose`: A reference to the close button inside the popup window.
+ * 		- `DOMSearchField`: A reference to the search field HTML element.
+ * 
+ * 	The following attributes are also defined:
+ * 
+ * 		- `keyTimeout`: A variable used to handle keyboard events.
+ * 		- `isActive`: A flag indicating whether the search panel is active or not.
+ * 		- `searchActive`: A flag indicating whether the search box is in use or not.
+ */
 function SearchBox(name, resultsPath, extension) {
   if (!name || !resultsPath) {  alert("Missing parameters to SearchBox."); }
   if (!extension || extension == "") { extension = ".html"; }
 
+  /**
+   * @description Calculates the x-coordinate of an element based on its offsetWidth
+   * property and parent-child relationships.
+   * 
+   * @param { `HTMLElement`. } item - element for which the left offset position is to
+   * be calculated.
+   * 
+   * 		- `offsetWidth`: A boolean property that indicates whether the `item` has an
+   * explicit width defined or not.
+   * 		- `offsetLeft`: A number property representing the left position of the `item`
+   * relative to its parent element in the Document Object Model (DOM).
+   * 		- `offsetParent`: A reference to the parent element of the `item` in the DOM.
+   * 
+   * @returns { integer } the total offset left of the element from the starting point.
+   */
   function getXPos(item) {
     let x = 0;
     if (item.offsetWidth) {
@@ -48,6 +101,16 @@ function SearchBox(name, resultsPath, extension) {
     return x;
   }
 
+  /**
+   * @description Calculates the position of an element relative to the document's body
+   * by traversing the element's parents and adding up their offset top values.
+   * 
+   * @param { object } item - element whose `offsetTop` value is calculated to determine
+   * its position on the page.
+   * 
+   * @returns { integer } the sum of the top positions of all parent elements until the
+   * document body is reached.
+   */
   function getYPos(item) {
     let y = 0;
     if (item.offsetWidth) {
@@ -348,8 +411,24 @@ function SearchBox(name, resultsPath, extension) {
 // -----------------------------------------------------------------------
 
 // The class that handles everything on the search results page.
+/**
+ * @description Manages a search results window's navigation through children elements
+ * based on arrow key presses. It handles keyboard input and calls child element's
+ * `Focus` method to focus on the appropriate element.
+ * 
+ * @returns { boolean } a boolean indicating whether the Enter key was pressed.
+ */
 function SearchResults() {
 
+  /**
+   * @description Takes a string `search` and converts each character to an identifier
+   * using a specific algorithm. The resulting string is returned as the converted identifier.
+   * 
+   * @param { string } search - search term that the function will convert into an identifier.
+   * 
+   * @returns { string } a unique identifier formed by concatenating uppercase letters,
+   * digits, and underscores based on the input search string.
+   */
   function convertToId(search) {
     let result = '';
     for (let i=0;i<search.length;i++) {
@@ -594,14 +673,49 @@ function SearchResults() {
   }
 }
 
+/**
+ * @description Generates and appends HTML elements containing search results to an
+ * existing `div` element with the id `SRResults`.
+ * 
+ * @param { string } resultsPath - URL path where the search results links should
+ * lead to when clicked.
+ */
 function createResults(resultsPath) {
 
+  /**
+   * @description Sets attribute values for an element based on an action string provided.
+   * It adds `onkeydown`, `onkeypress`, and `onkeyup` attributes with the given action
+   * value.
+   * 
+   * @param { element. } elem - HTML element for which the key actions are to be set.
+   * 
+   * 		- `elem`: This is the HTML element to which actions will be set for key events.
+   * 		- `action`: This is the action that will be triggered when a key event occurs
+   * on the `elem`.
+   * 
+   * @param { string } action - onkeydown, onkeypress and onkeyup event actions for the
+   * specified HTML element, which are added to the element's attribute list through
+   * the setKeyActions function call.
+   */
   function setKeyActions(elem,action) {
     elem.setAttribute('onkeydown',action);
     elem.setAttribute('onkeypress',action);
     elem.setAttribute('onkeyup',action);
   }
 
+  /**
+   * @description Sets the `class` or `className` attribute of an element to a given
+   * value, `attr`.
+   * 
+   * @param { HTML Element. } elem - HTML element to which the class attribute will be
+   * set.
+   * 
+   * 		- `attr`: A string that represents the value to be assigned as the class attribute
+   * for the element.
+   * 
+   * @param { string } attr - new value of the element's `class` attribute, which is
+   * then assigned to the element using the `setAttribute()` method.
+   */
   function setClassAttr(elem,attr) {
     elem.setAttribute('class',attr);
     elem.setAttribute('className',attr);
@@ -660,6 +774,12 @@ function createResults(resultsPath) {
   });
 }
 
+/**
+ * @description 1) creates links for search results and sets their `tabIndex`, 2)
+ * adds an event listener to a search input field, 3) handles keyboard inputs to
+ * toggle the search selection window, 4) retrieves the selected name from cookies
+ * and 5) calls the `OnSelectItem` method with the corresponding ID.
+ */
 function init_search() {
   const results = document.getElementById("MSearchSelectWindow");