Add documentation to XML based script

jzamora5 · Feb 13, 2021 · 378f0a8 · 378f0a8
1 parent 6be0627
commit 378f0a8
Showing 1 changed file with 100 additions and 0 deletions.
diff --git a/xml-scripts.js b/xml-scripts.js
@@ -1,5 +1,13 @@
 $(document).ready(function () {
   // XML TO OBJECT LIST =====================================================
+
+  /**
+   * Transfrom an XML object to a regular JSON like object
+   * @xml  {xml_object} xml to be transformed
+   * @key {string} value passed if a specific query must be
+   * done in XML
+   * @return {Array}  list of parsed data
+   */
   function XMLtoObjList(xml, key) {
     let list = [];
     let dic = {};
@@ -42,6 +50,11 @@ $(document).ready(function () {
   }
 
   //   Quotes ===============================================================
+  /**
+   * Creates a carousel item and appends it to the DOM
+   * @data  {Array} List of data to be displayed as Quotes
+   * @return {undefined}  No return
+   */
   function displayQuotes(data) {
     data = XMLtoObjList(data, "quote");
     let classItem = "";
@@ -76,6 +89,12 @@ $(document).ready(function () {
     // END OF displayQuotes
   }
 
+  /**
+   * Modifies to logic of bootstrap carousel in order for
+   * it to move 1 slide at a time
+   * @id  {string} Id of a carousel item slide
+   * @return {undefined}  No return
+   */
   function slideOne(id) {
     $(`#${id} .carousel-item`).each(function () {
       let minPerSlide = 4;
@@ -96,6 +115,11 @@ $(document).ready(function () {
     });
   }
 
+  /**
+   * Creates the string equivalent of a card element in bootstrap
+   * @cardData  {object} An object containing data for creating the card
+   * @return {string}  string equivalent of a card element in bootstrap
+   */
   function createCard(cardData) {
     let starState = "";
     let starString = "";
@@ -155,6 +179,12 @@ $(document).ready(function () {
     // END OF createCard
   }
 
+  /**
+   * Creates cards and attaches them to the DOM in order to display
+   * the Popular Videos section
+   * @data  {Arrray} list of data for creating cards
+   * @return {undefined}  no return
+   */
   function displayPopular(data) {
     data = XMLtoObjList(data, "video");
     let classItem = "";
@@ -175,6 +205,12 @@ $(document).ready(function () {
     // END OF displayPopular
   }
 
+  /**
+   * Creates cards and attaches them to the DOM in order to display
+   * the Latest Videos section
+   * @data  {Array} list of data for creating cards
+   * @return {undefined}  no return
+   */
   function displayLatest(data) {
     data = XMLtoObjList(data, "video");
     let classItem = "";
@@ -195,6 +231,12 @@ $(document).ready(function () {
     // END OF displayLatest
   }
 
+  /**
+   * Retrieves the needed data of the search bar in the DOM
+   * the popular section
+   * @return {object}  An object containing the different arguments of search
+   * in lowercase and without spaces
+   */
   function searchObject() {
     let searchObj = {
       q: $("#keywords-input").val(),
@@ -205,6 +247,12 @@ $(document).ready(function () {
     return searchObj;
   }
 
+  /**
+   * Creates cards and attaches them to the DOM in order to display
+   * the popular section
+   * @data  {Array} list of data for creating cards
+   * @return {undefined}  no return
+   */
   function searchRequest() {
     let searchObj = searchObject();
     let $results = $("#results-items");
@@ -216,13 +264,26 @@ $(document).ready(function () {
     }
   }
 
+  /**
+   * Returns title to original condition with corresponding
+   * caps and spaces
+   * @title  {string} title to be parsed
+   * @return {string}  parsed title
+   */
   function parseTitle(title) {
     if (title) {
       title = title.charAt(0).toUpperCase() + title.slice(1).replace("_", " ");
     }
     return title;
   }
 
+  /**
+   * Creates the dropdown menu with the corresponding options from the api
+   * @list  {Array} list of options to be displayed
+   * @$DOMElement  {list} DOM Element to attach the menu to
+   * @$titleElement  {list} corresponding title element in search bar of DOM
+   * @return {undefined}  no return
+   */
   function displayDropdown(list, $DOMElement, $titleElement) {
     if (list.length) {
       for (let l of list) {
@@ -239,6 +300,11 @@ $(document).ready(function () {
     }
   }
 
+  /**
+   * Removes unnecesary nodes in XML object
+   * @data  {xml_object} XML object
+   * @return {xml_object} cleaned xml object
+   */
   function cleanXML(data) {
     $(data).find("topics").remove();
     $(data).find("sorts").remove();
@@ -247,6 +313,12 @@ $(document).ready(function () {
     return data;
   }
 
+  /**
+   * Displays the whole search section in dom
+   * @data  {object} object containing information
+   * about the topics and sort options
+   * @return {undefined} no return
+   */
   function displaySearch(data) {
     let title;
     let topics = XMLtoObjList(data, "topic");
@@ -275,6 +347,11 @@ $(document).ready(function () {
     });
   }
 
+  /**
+   * Shows all of the videos, obtained after request to API, in DOM
+   * @data  {object} object containing result from API response
+   * @return {undefined}  no return
+   */
   function displayResults(data) {
     let courses = XMLtoObjList(data, "course");
     if (!courses) return;
@@ -296,13 +373,26 @@ $(document).ready(function () {
     }
   }
 
+  /**
+   * Calls the needed functions in order to correctly display
+   * the search options in dom and results from API response
+   * @data  {data} object containing data from API response
+   * @return {string}  parsed title
+   */
   function displaySearchAndResults(data) {
     displayResults(data);
     displaySearch(data);
 
     // END OF displayResults
   }
 
+  /**
+   * Function to show loader when waiting for API response
+   * @active  {boolean} indicates whether loader should be displayed or
+   * removed
+   * @id  {string} Id of DOM object to attach loader to
+   * @return {string}  parsed title
+   */
   function displayLoader(active, id) {
     if (active) {
       let $loader = $(`<div class="loader" id="loader-${id}"></div>`);
@@ -315,6 +405,16 @@ $(document).ready(function () {
     // END OF displayLoader
   }
 
+  /**
+   * Function to make GET request to API
+   * @url  {string} url of API endpoint
+   * @callback  {function} callback function to be executed
+   * and that depends on the section of the web page which is being
+   * generated by JS
+   * @id  {string} Value needed to display loader
+   * @data  {object} object to send in API request
+   * @return {string}  parsed title
+   */
   function requestData(url, callback, id, data = {}) {
     displayLoader(true, id);