Added comments to 42 functions across 12 files

TestDoc/html/clipboard.js

@@ -50,6 +50,10 @@ $(function() {
         navigator.clipboard.writeText(text);
         this.classList.add("success")
         this.innerHTML = clipboard_successIcon
+        /**
+         * @description removes a `success` class and displays an icon after a timeout period
+         * elapses.
+         */
         window.setTimeout(() => { // switch back to normal icon after timeout
             this.classList.remove("success")
             this.innerHTML = clipboard_icon

TestDoc/html/cookie.js

@@ -6,6 +6,19 @@
 let Cookie = {
   cookie_namespace: 'doxygen_',
 
+  /**
+   * @description retrieves a setting from either local storage or a cookie depending
+   * on the presence of Chrome. If the setting is not found, it returns the default value.
+   * 
+   * @param { string } cookie - name of a cookie that the function reads from the user's
+   * browser storage.
+   * 
+   * @param { string } defVal - default value to be returned if no value is found in
+   * the browser's local or session storage for the specified cookie.
+   * 
+   * @returns { string } the value of a setting stored in cookies or default value if
+   * 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 on the client-side with an optional expiration time in
+   * days. It stores the cookie in either localStorage or sessionStorage, depending on
+   * the value of the `days` parameter.
+   * 
+   * @param { string } cookie - name of the cookie to set or delete.
+   * 
+   * @param { string } val - value that is to be stored in the cookie.
+   * 
+   * @param { binary_expression } days - number of days that the cookie should be stored
+   * for, with 0 representing session storage, -1 denoting deletion, and any other value
+   * indicating storage for a specific number of days.
+   */
   writeSetting(cookie,val,days=10*365) { // default days='forever', 0=session cookie, -1=delete
     if (window.chrome) {
       if (days==0) {
@@ -44,6 +70,14 @@ let Cookie = {
     }
   },
 
+  /**
+   * @description removes a setting from storage if it exists in either local or session
+   * storage. If the setting is not found in either storage, it is set to an empty
+   * string and a negative value to indicate its absence.
+   * 
+   * @param { string } cookie - name of the setting to be erased from local or session
+   * storage.
+   */
   eraseSetting(cookie) {
     if (window.chrome) {
       if (localStorage.getItem(this.cookie_namespace+cookie)) {

TestDoc/html/menu.js

@@ -22,7 +22,45 @@
 
  @licend  The above is the entire license notice for the JavaScript code in this file
  */
+/**
+ * @description 1) generates HTML code for a menu and adds it to the page, 2) sets
+ * up an event listener for menu visibility changes, 3) initializes a search box and
+ * its CSS positioning, and 4) animates the menu's display when visibility changes.
+ * 
+ * @param { string } relPath - relative path of the menu from the server-side root
+ * directory, which is used to construct the HTML structure of the menu.
+ * 
+ * @param { boolean } searchEnabled - availability of search functionality in the
+ * menu, and affects the display of the search box and its corresponding actions.
+ * 
+ * @param { boolean } serverSide - server-side execution of the search functionality,
+ * affecting the way the search box is generated.
+ * 
+ * @param { string } searchPage - page to which the search results will be linked
+ * when the user performs a search from the menu, and it is passed to the `action`
+ * attribute of the form element in the code.
+ * 
+ * @param { string } search - search query, which is used to generate the HTML code
+ * for a search box and results window, based on whether server-side processing is
+ * enabled and what type of search is performed.
+ * 
+ * @returns { string } HTML code for a responsive menu with a search box.
+ */
 function initMenu(relPath,searchEnabled,serverSide,searchPage,search) {
+  /**
+   * @description takes an object `data` and a relative path `relPath`, recursively
+   * builds a tree-like structure by appending an `<ul>` element, followed by
+   * `data.children[i].text`, and then recursively calls itself to build the child nodes
+   * using the same process.
+   * 
+   * @param { object } data - node of a hierarchical data structure, which is traversed
+   * and recursively converted into an HTML list.
+   * 
+   * @param { string } relPath - relative path to the root directory of the tree, which
+   * is used to construct the HTML hierarchy of links for each node.
+   * 
+   * @returns { string } a nested HTML ul list containing child nodes represented as links.
+   */
   function makeTree(data,relPath) {
     let result='';
     if ('children' in data) {

TestDoc/html/navtree.js

@@ -23,6 +23,21 @@
  @licend  The above is the entire license notice for the JavaScript code in this file
  */
 
+/**
+ * @description initializes the navigation tree, showing the root node and its children
+ * upon page load or when the URL changes. It also sets up events for clicking on
+ * links and anchors to navigate the tree.
+ * 
+ * @param { string } toroot - 0-based index of the root node in the NavTree data
+ * structure, which is used to determine the correct navigation path and display the
+ * appropriate breadcrumbs when the user clicks on a link or enters a new URL.
+ * 
+ * @param { string } relpath - path to the current document, which is used to generate
+ * the correct URLs for navigating through the tree and for showing the node's children.
+ * 
+ * @returns { object } a responsive and interactive navigational tree based on a given
+ * URL hash.
+ */
 function initNavTree(toroot,relpath) {
   let navTreeSubIndices = [];
   const ARROW_DOWN = '▼';

TestDoc/html/resize.js

@@ -23,10 +23,22 @@
  @licend  The above is the entire license notice for the JavaScript code in this file
  */
 
+/**
+ * @description sets up a responsive layout for a side-nav menu, content area, and
+ * footer on page load. It listens for window resizes and horizontal drag gestures
+ * on the split bar to adjust widths of these elements, and uses cookies to keep track
+ * of the last width used for restoration.
+ */
 function initResizable() {
   let sidenav,navtree,content,header,footer,barWidth=6;
   const RESIZE_COOKIE_NAME = ''+'width';
 
+  /**
+   * @description adjusts the margin left of an element `content` based on the width
+   * of a side nav `sidenav`. If `page_layout` is defined and equal to 1, it also adjusts
+   * the margin left of a footer element. Finally, it writes a cookie with the difference
+   * between the width of the sidenav and the bar width to store for future reference.
+   */
   function resizeWidth() {
     const sidenavWidth = $(sidenav).outerWidth();
     content.css({marginLeft:parseInt(sidenavWidth)+"px"});
@@ -36,6 +48,13 @@ function initResizable() {
     Cookie.writeSetting(RESIZE_COOKIE_NAME,sidenavWidth-barWidth);
   }
 
+  /**
+   * @description restores the width of a sidebar and its contents based on the provided
+   * `navWidth`. It also adjusts the margin left of the footer, if applicable.
+   * 
+   * @param { integer } navWidth - width of the navigator and is used to set the margin
+   * left values for the content, footer, and sidenav elements in the CSS.
+   */
   function restoreWidth(navWidth) {
     content.css({marginLeft:parseInt(navWidth)+barWidth+"px"});
     if (typeof page_layout!=='undefined' && page_layout==1) {
@@ -44,6 +63,11 @@ function initResizable() {
     sidenav.css({width:navWidth + "px"});
   }
 
+  /**
+   * @description calculates and updates the heights of various elements on a web page
+   * based on the window height, and scrolls the element with the ID matching the hash
+   * fragment into view if present.
+   */
   function resizeHeight() {
     const headerHeight = header.outerHeight();
     const footerHeight = footer.outerHeight();
@@ -66,6 +90,10 @@ function initResizable() {
     }
   }
 
+  /**
+   * @description adjusts the width of a side nav based on the size of the window and
+   * a cookie setting, restoring the original width when the function is called.
+   */
   function collapseExpand() {
     let newWidth;
     if (sidenav.width()>0) {

TestDoc/html/search/search.js

@@ -33,10 +33,40 @@ const searchResults = new SearchResults();
           storing this instance.  Is needed to be able to set timeouts.
    resultPath - path to use for external files
 */
+/**
+ * @description handles user input and search results, including:
+ * 
+ * 	- Updating the search box with each character typed
+ * 	- Closing the results window and hiding the search box upon selection
+ * 	- Performing a search using the `Search` function, loading JavaScript files as needed
+ * 	- Handling empty search results by displaying an "empty search results" message.
+ * 
+ * @param { string } name - name attribute of the search form, which allows specifying
+ * a specific form element to trigger the search functionality when its value changes.
+ * 
+ * @param { string } resultsPath - path to the directory where the search results
+ * will be stored, and it is used to construct the URL for loading the JavaScript
+ * file containing the search results.
+ * 
+ * @param { string } extension - file extension to be searched, and is used in
+ * combination with the `searchValue` to filter the search results.
+ * 
+ * @returns { object } a JavaScript function that performs a search based on the
+ * user's input and displays the results in a popup window.
+ */
 function SearchBox(name, resultsPath, extension) {
   if (!name || !resultsPath) {  alert("Missing parameters to SearchBox."); }
   if (!extension || extension == "") { extension = ".html"; }
 
+  /**
+   * @description calculates and returns the x-coordinate of an element relative to the
+   * document's body, based on its offsetLeft properties within its own hierarchy of parents.
+   * 
+   * @param { object } item - DOM element for which the left position is to be calculated.
+   * 
+   * @returns { integer } the sum of the left offsets of all elements from the current
+   * element to the document body.
+   */
   function getXPos(item) {
     let x = 0;
     if (item.offsetWidth) {
@@ -48,6 +78,20 @@ function SearchBox(name, resultsPath, extension) {
     return x;
   }
 
+  /**
+   * @description calculates the top position of an element relative to its containing
+   * block, taking into account any nested offsets within its parents.
+   * 
+   * @param { `HTMLElement`. } item - DOM element for which the top position needs to
+   * be calculated.
+   * 
+   * 		- `offsetWidth`: This property represents the width of the element in pixels.
+   * It is used to calculate the distance from the top of the container element to the
+   * bottom of the element.
+   * 
+   * @returns { integer } the total sum of the offsetTop values of all elements from
+   * the starting item to the document body.
+   */
   function getYPos(item) {
     let y = 0;
     if (item.offsetWidth) {
@@ -348,8 +392,29 @@ function SearchBox(name, resultsPath, extension) {
 // -----------------------------------------------------------------------
 
 // The class that handles everything on the search results page.
+/**
+ * @description manages the results window for a search box, handling keyboard input
+ * to navigate and focus on child elements. It provides event listeners for `keydown`,
+ * `keypress`, and `keyup` to navigate through child elements and focus them based
+ * on user input.
+ * 
+ * @returns { boolean } a list of search results with an index and a corresponding
+ * element from the main list.
+ */
 function SearchResults() {
 
+  /**
+   * @description transforms a search query into an identifier by replacing non-alphanumeric
+   * characters with underscores and representing non-ASCII characters as hexadecimal
+   * codes.
+   * 
+   * @param { string } search - text to be converted into an identifier, and its
+   * characters are manipulated based on their codes to produce the resulting identifier.
+   * 
+   * @returns { string } a unique identifier string consisting of lowercase letters and
+   * digits, generated by replacing non-alpha-numeric characters with underscores
+   * followed by their hexadecimal code values.
+   */
   function convertToId(search) {
     let result = '';
     for (let i=0;i<search.length;i++) {
@@ -594,14 +659,56 @@ function SearchResults() {
   }
 }
 
+/**
+ * @description generates and appends HTML elements with search results to an element
+ * with an ID of "SRResults". It loops through an array of search results, creating
+ * a new `div` element for each result, and sets various attributes such as class and
+ * ID.
+ * 
+ * @param { string } resultsPath - path to the results page where the search links
+ * will navigate to after being clicked, and it is used in the `href` attribute of
+ * each link element inside the `srLink` element.
+ */
 function createResults(resultsPath) {
 
+  /**
+   * @description sets the `onkeydown`, `onkeypress`, and `onkeyup` attributes of an
+   * element (represented by the `elem` parameter) to a given action (represented by
+   * the `action` parameter).
+   * 
+   * @param { element. } elem - HTML element to which the `setKeyActions` function will
+   * apply the specified action(s).
+   * 
+   * 		- `setAttribute`: This method is used to set attribute values for an element.
+   * In this function, it is used to set the `onkeydown`, `onkeypress`, and `onkeyup`
+   * attributes of `elem`.
+   * 
+   * @param { string } action - onKeyDown, onKeyPress, or onKeyUp event handler to be
+   * assigned to an HTML element via the `setAttribute()` method within the `setKeyActions()`
+   * function.
+   */
   function setKeyActions(elem,action) {
     elem.setAttribute('onkeydown',action);
     elem.setAttribute('onkeypress',action);
     elem.setAttribute('onkeyup',action);
   }
 
+  /**
+   * @description updates an element's class attribute by setting its value to a given
+   * string argument, and also sets the "className" attribute with the same value for
+   * backup purposes.
+   * 
+   * @param { element. } elem - HTML element for which the class attribute is being set.
+   * 
+   * 		- ` elem`: The object to which the `class` attribute is being set. It may have
+   * other properties as well.
+   * 		- `attr`: The value to be assigned to the `class` attribute. It can be a string
+   * or any type of data that can be serialized into a string.
+   * 
+   * @param { string } attr - new value for the class attribute of an HTML element,
+   * which is set to the element via the `setAttribute()` method in the `setClassAttr()`
+   * function.
+   */
   function setClassAttr(elem,attr) {
     elem.setAttribute('class',attr);
     elem.setAttribute('className',attr);
@@ -660,6 +767,12 @@ function createResults(resultsPath) {
   });
 }
 
+/**
+ * @description initializes and prepares the search selection window for use, including
+ * adding clickable labels to a HTML element and setting up event listeners for
+ * keyboard input. It also retrieves and sets the current search selection based on
+ * a cookie value and calls the `OnSelectItem` method with the corresponding ID.
+ */
 function init_search() {
   const results = document.getElementById("MSearchSelectWindow");
 

html/clipboard.js

@@ -50,6 +50,10 @@ $(function() {
         navigator.clipboard.writeText(text);
         this.classList.add("success")
         this.innerHTML = clipboard_successIcon
+        /**
+         * @description clears any success class applied to an element and replaces its
+         * innerHTML with a custom icon representing a cliboard.
+         */
         window.setTimeout(() => { // switch back to normal icon after timeout
             this.classList.remove("success")
             this.innerHTML = clipboard_icon