UTI: Code clean-up

Change-Id: Ia88f3ce646664eeb4f2bb96e25fe1c2e433d7423
Signed-off-by: Tibor Frank <tifrank@cisco.com>

2 files changed, 163 insertions, 9 deletions

diff --git a/resources/tools/dash/app/pal/trending/layout.py b/resources/tools/dash/app/pal/trending/layout.py
index 0fe28ebed5..797bf6a4f5 100644
--- a/resources/tools/dash/app/pal/trending/layout.py
+++ b/resources/tools/dash/app/pal/trending/layout.py
@@ -40,13 +40,36 @@ from .graphs import graph_trending, graph_hdrh_latency, \
 
 
 class Layout:
-    """
+    """The layout of the dash app and the callbacks.
     """
 
     def __init__(self, app: Flask, html_layout_file: str,
         graph_layout_file: str, data_spec_file: str, tooltip_file: str,
         time_period: str=None) -> None:
-        """
+        """Initialization:
+        - save the input parameters,
+        - read and pre-process the data,
+        - prepare data for the control panel,
+        - read HTML layout file,
+        - read tooltips from the tooltip file.
+
+        :param app: Flask application running the dash application.
+        :param html_layout_file: Path and name of the file specifying the HTML
+            layout of the dash application.
+        :param graph_layout_file: Path and name of the file with layout of
+            plot.ly graphs.
+        :param data_spec_file: Path and name of the file specifying the data to
+            be read from parquets for this application.
+        :param tooltip_file: Path and name of the yaml file specifying the
+            tooltips.
+        :param time_period: It defines the time period for data read from the
+            parquets in days from now back to the past.
+        :type app: Flask
+        :type html_layout_file: str
+        :type graph_layout_file: str
+        :type data_spec_file: str
+        :type tooltip_file: str
+        :type time_period: int
         """
 
         # Inputs
@@ -200,8 +223,19 @@ class Layout:
         return self._time_period
 
     def add_content(self):
+        """Top level method which generated the web page.
+
+        It generates:
+        - Store for user input data,
+        - Navigation bar,
+        - Main area with control panel and ploting area.
+
+        If no HTML layout is provided, an error message is displayed instead.
+
+        :returns: The HTML div with the whole page.
+        :rtype: html.Div
         """
-        """
+
         if self.html_layout and self.spec_tbs:
             return html.Div(
                 id="div-main",
@@ -254,6 +288,9 @@ class Layout:
 
     def _add_navbar(self):
         """Add nav element with navigation panel. It is placed on the top.
+
+        :returns: Navigation bar.
+        :rtype: dbc.NavbarSimple
         """
         return dbc.NavbarSimple(
             id="navbarsimple-main",
@@ -276,6 +313,9 @@ class Layout:
 
     def _add_ctrl_col(self) -> dbc.Col:
         """Add column with controls. It is placed on the left side.
+
+        :returns: Column with the control panel.
+        :rtype: dbc.Col
         """
         return dbc.Col(
             id="col-controls",
@@ -286,6 +326,9 @@ class Layout:
 
     def _add_plotting_col(self) -> dbc.Col:
         """Add column with plots and tables. It is placed on the right side.
+
+        :returns: Column with tables.
+        :rtype: dbc.Col
         """
         return dbc.Col(
             id="col-plotting-area",
@@ -320,7 +363,10 @@ class Layout:
         )
 
     def _add_ctrl_panel(self) -> dbc.Row:
-        """
+        """Add control panel.
+
+        :returns: Control panel.
+        :rtype: dbc.Row
         """
         return dbc.Row(
             id="row-ctrl-panel",
@@ -625,7 +671,19 @@ class Layout:
         )
 
     class ControlPanel:
+        """A class representing the control panel.
+        """
+
         def __init__(self, panel: dict) -> None:
+            """Initialisation of the control pannel by default values. If
+            particular values are provided (parameter "panel") they are set
+            afterwards.
+
+            :param panel: Custom values to be set to the control panel.
+            :param default: Default values to be set to the control panel.
+            :type panel: dict
+            :type defaults: dict
+            """
 
             # Defines also the order of keys
             self._defaults = {
@@ -670,6 +728,13 @@ class Layout:
             return self._panel
 
         def set(self, kwargs: dict) -> None:
+            """Set the values of the Control panel.
+
+            :param kwargs: key - value pairs to be set.
+            :type kwargs: dict
+            :raises KeyError: If the key in kwargs is not present in the Control
+                panel.
+            """
             for key, val in kwargs.items():
                 if key in self._panel:
                     self._panel[key] = val
@@ -677,15 +742,42 @@ class Layout:
                     raise KeyError(f"The key {key} is not defined.")
 
         def get(self, key: str) -> any:
+            """Returns the value of a key from the Control panel.
+
+            :param key: The key which value should be returned.
+            :type key: str
+            :returns: The value of the key.
+            :rtype: any
+            :raises KeyError: If the key in kwargs is not present in the Control
+                panel.
+            """
             return self._panel[key]
 
         def values(self) -> tuple:
+            """Returns the values from the Control panel as a list.
+
+            :returns: The values from the Control panel.
+            :rtype: list
+            """
             return tuple(self._panel.values())
 
     def callbacks(self, app):
+        """Callbacks for the whole application.
+
+        :param app: The application.
+        :type app: Flask
+        """
 
         def _generate_plotting_area(figs: tuple, url: str) -> tuple:
-            """
+            """Generate the plotting area with all its content.
+
+            :param figs: Figures to be placed in the plotting area.
+            :param utl: The URL to be placed in the plotting area bellow the
+                tables.
+            :type figs: tuple of plotly.graph_objects.Figure
+            :type url: str
+            :returns: tuple of elements to be shown in the plotting area.
+            :rtype: tuple(dcc.Graph, dcc.Graph, list(dbc.Col, dbc.Col))
             """
 
             (fig_tput, fig_lat) = figs
@@ -810,7 +902,53 @@ class Layout:
             cl_testtype: list, cl_testtype_all: list, cl_normalize: list,
             btn_add: int, d_start: str, d_end: str, btn_remove: int,
             btn_remove_all: int, href: str) -> tuple:
-            """
+            """Update the application when the event is detected.
+
+            :param cp_data: Current status of the control panel stored in
+                browser.
+            :param store_sel: List of tests selected by user stored in the
+                browser.
+            :param list_sel: List of tests selected by the user shown in the
+                checklist.
+            :param dd_dut: Input - DUTs.
+            :param dd_phy: Input - topo- arch-nic-driver.
+            :param dd_area: Input - Tested area.
+            :param dd_test: Input - Test.
+            :param cl_core: Input - Number of cores.
+            :param cl_core_all: Input - All numbers of cores.
+            :param cl_framesize: Input - Frame sizes.
+            :param cl_framesize_all: Input - All frame sizes.
+            :param cl_testtype: Input - Test type (NDR, PDR, MRR).
+            :param cl_testtype_all: Input - All test types.
+            :param cl_normalize: Input - Normalize the results.
+            :param btn_add: Input - Button "Add Selected" tests.
+            :param d_start: Date and time where the data processing starts.
+            :param d_end: Date and time where the data processing ends.
+            :param btn_remove: Input - Button "Remove selected" tests.
+            :param btn_remove_all: Input - Button "Remove All" tests.
+            :param href: Input - The URL provided by the browser.
+            :type cp_data: dict
+            :type store_sel: list
+            :type list_sel: list
+            :type dd_dut: str
+            :type dd_phy: str
+            :type dd_area: str
+            :type dd_test: str
+            :type cl_core: list
+            :type cl_core_all: list
+            :type cl_framesize: list
+            :type cl_framesize_all: list
+            :type cl_testtype: list
+            :type cl_testtype_all: list
+            :type cl_normalize: list
+            :type btn_add: int
+            :type d_start: str
+            :type d_end: str
+            :type btn_remove: int
+            :type btn_remove_all: int
+            :type href: str
+            :returns: New values for web page elements.
+            :rtype: tuple
             """
 
             ctrl_panel = self.ControlPanel(cp_data)
@@ -1150,7 +1288,14 @@ class Layout:
             prevent_initial_call=True
         )
         def _show_metadata_from_graphs(graph_data: dict) -> tuple:
-            """
+            """Generates the data for the offcanvas displayed when a particular
+            point in a graph is clicked on.
+
+            :param graph_data: The data from the clicked point in the graph.
+            :type graph_data: dict
+            :returns: The data to be displayed on the offcanvas and the
+                information to show the offcanvas.
+            :rtype: tuple(list, list, bool)
             """
             try:
                 trigger_id = loads(
@@ -1220,7 +1365,16 @@ class Layout:
             prevent_initial_call=True
         )
         def _download_data(store_sel, n_clicks):
-            """
+            """Download the data
+
+            :param store_sel: List of tests selected by user stored in the
+                browser.
+            :param n_clicks: Number of clicks on the button "Download".
+            :type store_sel: list
+            :type n_clicks: int
+            :returns: dict of data frame content (base64 encoded) and meta data
+                used by the Download component.
+            :rtype: dict
             """
 
             if not n_clicks:
diff --git a/resources/tools/dash/app/pal/trending/trending.py b/resources/tools/dash/app/pal/trending/trending.py
index 3697f7150f..af1dc79722 100644
--- a/resources/tools/dash/app/pal/trending/trending.py
+++ b/resources/tools/dash/app/pal/trending/trending.py
@@ -11,7 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Instantiate the Trending Dash applocation.
+"""Instantiate the Trending Dash application.
 """
 import dash