commit 70a3df53e825318b2c742019cfc5fe3b17105091
Author: vastja <vastja@students.zcu.cz>
Date:   Wed May 27 12:03:44 2020 +0000

    + Re #8086
    + php refactoring and comments

diff --git a/website/public/js/zcu-heatmap.js b/website/public/js/zcu-heatmap.js
index 9fe0dd5..099a6bb 100644
--- a/website/public/js/zcu-heatmap.js
+++ b/website/public/js/zcu-heatmap.js
@@ -17,6 +17,9 @@ var timer
 var isAnimationRunning = false
 var data = []
 
+var info = []
+var currenInfo = 0
+
 // holds all instances of markers for bind/unbind popup purpose
 // contains: {key:[L.circle,L.pupup]}
 // key: x and y, x + '' + y string
@@ -51,6 +54,9 @@ const genPopUp = (place, number, sum, currentPos, maxPos) => {
   ${genPopUpControls([previousButton, posInfo, nextButton])}
   `
 }
+/**
+ * Initialize leaflet map on start position which can be default or set based on user action
+ */
 // eslint-disable-next-line no-unused-vars
 function initMap () {
   startX = localStorage.getItem('lat') || startX
@@ -67,8 +73,6 @@ function initMap () {
   mymap.on('click', showInfo)
 }
 
-var info = []
-var currenInfo = 0
 
 function showInfo (e) {
   info = []
@@ -137,6 +141,9 @@ function setMapView (latitude, longitude, zoom) {
   mymap.setView([latitude, longitude], zoom)
 }
 
+/**
+ * Change animation start from playing to stopped or the other way round
+ */
 // eslint-disable-next-line no-unused-vars
 function changeAnimationState () {
   isAnimationRunning = !isAnimationRunning
@@ -173,6 +180,9 @@ function next () {
   changeUrl()
 }
 
+/**
+ * Change browser url based on animation step
+ */
 function changeUrl () {
   window.history.pushState(
     '',
@@ -190,6 +200,11 @@ function setTimeline () {
   $('#timeline').attr('class', 'time hour-' + currentTime)
 }
 
+/**
+ * Load and display heatmap layer for current data
+ * @param {string} opendataRoute route to dataset source
+ * @param {string} positionsRoute  route to dataset postitions source
+ */
 // eslint-disable-next-line no-unused-vars
 function loadCurrentTimeHeatmap (opendataRoute, positionsRoute) {
   dataSourceRoute = opendataRoute
@@ -292,6 +307,10 @@ function drawHeatmap (data) {
   // $(.leaflet-heatmap-layer).css('opacity', 'value');
 }
 
+/**
+ * Checks dataset availibility
+ * @param {string} route authority for datasets availibility checks 
+ */
 // eslint-disable-next-line no-unused-vars
 function checkDataSetsAvailability (route) {
   $.ajax({
diff --git a/website/src/Controller/HeatmapController.php b/website/src/Controller/HeatmapController.php
index 2a420de..c25d7f5 100644
--- a/website/src/Controller/HeatmapController.php
+++ b/website/src/Controller/HeatmapController.php
@@ -11,6 +11,10 @@ use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
 class HeatmapController extends AbstractController {
     /**
+     * Map page controller.
+     *
+     * @param IOpenDataManager $manager connection to database autowired
+     *
      * @Route("/heatmap", name="heatmap")
      */
     public function index(Request $request, IOpenDataManager $manager) {
@@ -22,7 +26,9 @@ class HeatmapController extends AbstractController {
         $isSubmitted = $form->isSubmitted();
         if ($isSubmitted) {
             $dataSet = $form->getData();
+            // Chceck whether the data is valid i.e. such a collection exists
             if (false == $manager->isCollectionAvailable($dataSet->getType(), $dataSet->getDate())) {
+                // Not? Populate form with empty data
                 $dataSet = new DataSet();
             }
             $form = $this->createForm(DataSetType::class, $dataSet);
@@ -39,6 +45,15 @@ class HeatmapController extends AbstractController {
     }
 
     /**
+     * Provides specific dataset information i.e. position, number and other informations depending on data type.
+     *
+     * @param IOpenDataManager $manager connection to database autowired
+     * @param string           $name    dataset name
+     * @param string           $date    dataset date in format YYYY-mm-dd
+     * @param string           $time    dataset time, number between 0 - 23
+     *
+     * @return json with dataset information
+     *
      * @Route("heatmap/opendata/{name}/{date}/{time}", name="opendata")
      */
     public function opendata(IOpenDataManager $manager, $name = 'NONE', $date = '2020-01-01', $time = '1') {
@@ -49,6 +64,13 @@ class HeatmapController extends AbstractController {
     }
 
     /**
+     * Provides available datasets in given date.
+     *
+     * @param IOpenDataManager $manager connection to database autowired
+     * @param string           $date    dataset date in format YYYY-mm-dd
+     *
+     * @return json with available datasets names
+     *
      * @Route("heatmap/available/{date}", name="available")
      */
     public function availableDatasets(IOpenDataManager $manager, $date = '2020-01-01') {
@@ -56,6 +78,12 @@ class HeatmapController extends AbstractController {
     }
 
     /**
+     * Provides dates with at least one available dataset.
+     *
+     * @param IOpenDataManager $manager connection to database
+     *
+     * @return json with dates with at least one available dataset in format YYYY-mm-dd
+     *
      * @Route("heatmap/dates", name="dates")
      */
     public function datesWithAvailableDatasets(IOpenDataManager $manager) {
@@ -63,6 +91,13 @@ class HeatmapController extends AbstractController {
     }
 
     /**
+     * Provides for dataset with given name all locations.
+     *
+     * @param IOpenDataManager $manager connection to database autowired
+     * @param string           $name    dataset name
+     *
+     * @return json with all locations for dataset with given name as [x => lat, y => lng]
+     *
      * @Route("heatmap/positions/{name}", name="positions")
      */
     public function dataSourcePoistions(IOpenDataManager $manager, $name = 'NONE') {
@@ -70,6 +105,12 @@ class HeatmapController extends AbstractController {
     }
 
     /**
+     * Provides last available date for each available dataset type.
+     *
+     * @param IOpenDataManager $manager connection to database autowired
+     *
+     * @return json with last available date for each available dataset type as [collection-type-name => YYYY-mm-dd]
+     *
      * @Route("heatmap/last", name="last")
      */
     public function lastAvailableCollections(IOpenDataManager $manager) {
diff --git a/website/src/Controller/HomeController.php b/website/src/Controller/HomeController.php
index 9c3d89f..327ac61 100644
--- a/website/src/Controller/HomeController.php
+++ b/website/src/Controller/HomeController.php
@@ -7,6 +7,8 @@ use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
 class HomeController extends AbstractController {
     /**
+     * Home page controller.
+     *
      * @Route("/", name="home")
      */
     public function index() {
diff --git a/website/src/Entity/DataSet.php b/website/src/Entity/DataSet.php
index 4e3be69..30bb44f 100644
--- a/website/src/Entity/DataSet.php
+++ b/website/src/Entity/DataSet.php
@@ -2,7 +2,11 @@
 
 namespace App\Entity;
 
-//Todo some checks
+/**
+ * Class wich represent From on heatmap page and is bind to that form.
+ *
+ * @see https://symfony.com/doc/current/forms.html
+ */
 class DataSet {
     protected $time;
     protected $date;
diff --git a/website/src/Form/DataSetType.php b/website/src/Form/DataSetType.php
index 328ceab..5fce92f 100644
--- a/website/src/Form/DataSetType.php
+++ b/website/src/Form/DataSetType.php
@@ -5,9 +5,7 @@ namespace App\Form;
 use App\Utils\Utils;
 use App\Entity\DataSet;
 use App\Repository\IOpenDataManager;
-use Symfony\Component\Form\FormView;
 use Symfony\Component\Form\AbstractType;
-use Symfony\Component\Form\FormInterface;
 use Symfony\Component\Form\FormBuilderInterface;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Component\Form\Extension\Core\Type\TextType;
@@ -15,15 +13,25 @@ use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
 use Symfony\Component\Form\Extension\Core\Type\SubmitType;
 
 class DataSetType extends AbstractType {
+    /**
+     * @var IOpenDataManager autowired connection to database
+     */
     private $manager;
 
+    /**
+     * @param IOpenDataManager autowired connection to database
+     */
     public function __construct(IOpenDataManager $manager) {
         $this->manager = $manager;
     }
 
+    /**
+     * @see https://symfony.com/doc/current/forms.html
+     */
     public function buildForm(FormBuilderInterface $builder, array $options) {
         $builder
             ->add('date', TextType::class)
+            // Populate time select with data
             ->add('time', ChoiceType::class, [
                 'choices' => [
                     '0:00-1:00' => 0,
@@ -52,20 +60,20 @@ class DataSetType extends AbstractType {
                     '23:00-0:00' => 23,
                 ],
             ])
+            // Populet type select with data
             ->add('type', ChoiceType::class, [
                 'choices' => Utils::prepareDatasetsNames($this->manager->getAvailableCollections()),
             ])
             ->add('submit', SubmitType::class);
     }
 
+    /**
+     * @see https://symfony.com/doc/current/forms.html
+     */
     public function configureOptions(OptionsResolver $resolver) {
         $resolver->setDefaults([
             'data_class' => DataSet::class,
             'method' => 'GET',
         ]);
     }
-
-    // public function buildView(FormView $view, Forminterface $form, array $options) {
-
-    // }
 }
diff --git a/website/src/Repository/IOpenDataManager.php b/website/src/Repository/IOpenDataManager.php
index 589a326..60027c5 100644
--- a/website/src/Repository/IOpenDataManager.php
+++ b/website/src/Repository/IOpenDataManager.php
@@ -2,20 +2,78 @@
 
 namespace App\Repository;
 
+/**
+ * interface for database connection management
+ * autowired @see website/config/services.yaml and https://symfony.com/doc/current/service_container/autowiring.html.
+ */
 interface IOpenDataManager {
+    /**
+     * Provides specific dataset information i.e. position, number and other informations depending on data type.
+     *
+     * @param string $name dataset name
+     * @param string $date dataset date in format YYYY-mm-dd
+     * @param string $hour dataset hour, number between 0 - 23
+     *
+     * @return array with dataset information
+     */
     public function getCollectionDataByName($name, $date, $hour);
 
+    /**
+     * Provides all available data sets types.
+     *
+     * @return array with avalable datasets names
+     */
     public function getAvailableCollections();
 
+    /**
+     * Provides available datasets in given date.
+     *
+     * @param string $date dataset date in format YYYY-mm-dd
+     *
+     * @return array with available datasets names
+     */
     public function getAvailableCollectionsByDay($date);
 
+    /**
+     * Check if dataset with given name is available for given date.
+     *
+     * @param string $name dataset name
+     * @param string $date dataset date in format YYYY-mm-dd
+     *
+     * @return bool true if dataset with given name is available in given date otherwise false
+     */
     public function isCollectionAvailable($name, $date);
 
+    /**
+     * Provides dates with at least one available dataset.
+     *
+     * @return array with dates with at least one available dataset in format YYYY-mm-dd
+     */
     public function getDatesWithAvailableCollection();
 
+    /**
+     * Provides max value of all locations (data dources) in dataset with given date on given date.
+     *
+     * @param string $name dataset name
+     * @param string $date dataset date in format YYYY-mm-dd
+     *
+     * @return number max value of all locations (data dources) in dataset with given date on given date
+     */
     public function getMaxCollectionNumberAtDay($name, $date);
 
+    /**
+     * Provides for dataset with given name all locations.
+     *
+     * @param string $name dataset name
+     *
+     * @return array with all locations for dataset with given name as [x => lat, y => lng]
+     */
     public function getDataSourcePositions($name);
 
+    /**
+     * Provides last available date for each available dataset type.
+     *
+     * @return array with last available date for each available dataset type as [collection-type-name => YYYY-mm-dd]
+     */
     public function getLastAvailableCollections();
 }
diff --git a/website/src/Repository/OpenDataManager.php b/website/src/Repository/OpenDataManager.php
index b4f346d..3e907d9 100644
--- a/website/src/Repository/OpenDataManager.php
+++ b/website/src/Repository/OpenDataManager.php
@@ -5,13 +5,24 @@ namespace App\Repository;
 use MongoDB\Driver\Query;
 use MongoDB\Driver\Manager;
 
+/**
+ * Implementation of IOpenDataManager
+ * autowired @see website/config/services.yaml and https://symfony.com/doc/current/service_container/autowiring.html.
+ *
+ * @see IOpenDataManager for methods comments
+ */
 class OpenDataManager implements IOpenDataManager {
+    /**
+     * @var IOpenDataManager autowired connection to database
+     */
     private $manager;
 
+    /**
+     * @param IOpenDataManager autowired connection to database
+     */
     public function __construct($connectionString) {
         $this->manager = new Manager(
             $connectionString
-            // $_ENV['DATABASE_CONNECTION_STRING']
         );
     }
 
@@ -20,9 +31,11 @@ class OpenDataManager implements IOpenDataManager {
             return [];
         }
 
+        // Number has to be two digit
         $valh = $hour < 10 ? '0'.$hour : $hour;
         $openData = $this->manager->executeQuery('open-data-db.'.$name.$date, new Query(['date' => $date.'-'.$valh], []));
 
+        // Converts result to php array
         $openData->setTypeMap([
             'array' => 'array',
             'document' => 'array',
@@ -35,6 +48,7 @@ class OpenDataManager implements IOpenDataManager {
     public function getAvailableCollections() {
         $openData = $this->manager->executeQuery('open-data-db.DATASETS', new Query([], ['projection' => ['key-name' => 1, 'display-name' => 1, '_id' => 0]]));
 
+        // Converts result to php array
         $openData->setTypeMap([
             'array' => 'array',
             'document' => 'array',
@@ -104,6 +118,7 @@ class OpenDataManager implements IOpenDataManager {
 
         $max = $this->manager->executeQuery('open-data-db.'.$name.$date, new Query([], ['sort' => ['number' => -1], 'limit' => 1]));
 
+        // Converts result to php array
         $max->setTypeMap([
             'array' => 'array',
             'document' => 'array',
@@ -122,6 +137,7 @@ class OpenDataManager implements IOpenDataManager {
 
         $positions = $this->manager->executeQuery('open-data-db.'.$name.'DEVICES', new Query([], []));
 
+        // Converts result to php array
         $positions->setTypeMap([
             'array' => 'array',
             'document' => 'array',
diff --git a/website/src/Utils/Utils.php b/website/src/Utils/Utils.php
index 92a70ee..a26d3e8 100644
--- a/website/src/Utils/Utils.php
+++ b/website/src/Utils/Utils.php
@@ -2,7 +2,18 @@
 
 namespace App\Utils;
 
+/**
+ * Class for static helper functions.
+ */
 class Utils {
+    /**
+     * Transforms array of arrays in form [['display-name' => whatever, 'key-name' => whatever, ...], ...]
+     * to simple array in form [dataset-display-name => dataset-key-name, ...].
+     *
+     * @param array of arrays for tranformation
+     *
+     * @return array in form [dataset-display-name => dataset-key-name, ...]
+     */
     public static function prepareDatasetsNames($datasets) {
         $names = [];
 
