DOC, STY: in code documentation and styling for readablility

Test Environment

automated tests

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related issues
• Up-to-date CHANGELOG.md (or not necessary)
• Up-to-date JSON schema (or not necessary)
• Appropriate user and developer documentation (or not necessary)
  • How do I use the software? Assume "stupid" users.
  • How do I develop or debug the software? Assume novice developers.
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md (or not necessary)
• Appropriate user and developer documentation (or not necessary)
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there specifications? Are they satisfied?

For further good practices have a look at our review guidelines.

procedures/query/applyPOV.sql

@@ -34,30 +34,31 @@ DELIMITER //
  * ----------
  *
  * versioned : boolean
- *   If True, sourceSet and targetSet have an _iversion column, otherwise that column will be
-*    ignored (or only HEAD will be inserted into targetSet).
+ * If True, sourceSet and targetSet have an _iversion column, otherwise that column will be ignored
+ * (or only HEAD will be inserted into targetSet).
  */
-CREATE PROCEDURE db_5_0.applyPOV(in sourceSet VARCHAR(255), /* (?) Name of the table that the POV will be applied to. This can be a temporary table. */
-                                 in targetSet VARCHAR(255), /* (?) Name of the result table of this POV. */
+CREATE PROCEDURE db_5_0.applyPOV(in sourceSet VARCHAR(255), /* Name of the table that the POV will be applied to. This can be a temporary table or the `entities` table */
+                                 in targetSet VARCHAR(255), /* Name of the result table of this POV. After the filter has been applied this table only contains matching
+                                entity ids. This may be NULL or same as sourceSet. In that case the filter is applied in-place (delete non-matching). Otherwise the filter is applied by copying only the matching ids from the *source* set to the *target* set. */
                                  in propertiesTable VARCHAR(255),
-                                 in refIdsTable VARCHAR(255),
+                                 in refIdsTable VARCHAR(255), /* Name of a tmp table that contains all ids of children of the value interpreted as entity name or id */
                                  in o CHAR(4), /* The operator for this operation. can be one of:
                                                     0   check for "equals NULL"
                                                     !0  check for "not NULL"
                                                     ->  check whether a reference exists
-                                                    (   (?) check for datetime intervals
-                                                    !(  (?) check for being outside of datetime intervals
-                                                    other operators (all SQL operators (?))
+                                                    (   check for datetime interval (say "in")
+                                                    !(  check for being outside of datetime intervals (say "not in")
+                                                    other operators (all valid SQL operators)
                                                       these other operators can be used either with or without an aggregation
                                                       to use an aggregation set agg to non-zero
                                                       all SQL aggregations can be used
                                                */
-                                 in vText VARCHAR(255),  /* (?) the text value to be checked against using operator o */
+                                 in vText VARCHAR(255),  /* the text value to be checked against using operator o */
                                  in vInt INT,  /* the integer value to be checked against using operator o */
                                  in vDouble DOUBLE,  /* the double value to be checked against using operator o */
-                                 in unit_sig BIGINT,
+                                 in unit_sig BIGINT, /* signatur of the unit given by the user. used when we need to convert units. */
                                  in vDoubleStdUnit DOUBLE, /* The numeric value, converted according to the unit rules. */
-                                 in stdUnit_sig BIGINT,
+                                 in stdUnit_sig BIGINT, /* signatur of the normalized/standardized unit, e.g when unit_sig is "km/h" this might be "m/s". */
                                  in vDateTime VARCHAR(255),
                                  in vDateTimeDotNotation VARCHAR(255),
                                  in agg CHAR(3), /* an SQL aggregate function or NULL when no aggregation should be used */
@@ -81,6 +82,10 @@ POV_LABEL: BEGIN
     DECLARE keepTabl VARCHAR(255) DEFAULT NULL;
     DECLARE existence_op VARCHAR(255) DEFAULT "EXISTS";
 
+        #-- ######### HINT ##############
+        #-- first the appropriate statement is created which in the end prepared and executed
+        #-- #############################
+
     IF o = '->' THEN
         #-- special case: pure reference property
         call applyRefPOV(sourceSet,targetSet, propertiesTable, refIdsTable, versioned);
@@ -229,6 +234,8 @@ POV_LABEL: BEGIN
             IF o = "!=" AND refIdsTable IS NOT NULL THEN
                 SET existence_op = "NOT EXISTS";
             END IF;
+			/* select all entities that reference the entity or a child of the
+			 * value interpreted as ID*/
             SET sRefData = IF(vText IS NULL,
                 ' UNION ALL SELECT DISTINCT domain_id, entity_id, property_id FROM `reference_data`',
                 IF(refIdsTable IS NULL,
@@ -243,6 +250,7 @@ POV_LABEL: BEGIN
 
     END IF;
 
+    #-- create array of statement parts (and replace null with empty string) (?)
     SET data = CONCAT('(',sTextData,
                 IF(sNameData IS NULL, '', sNameData),
                 IF(sEnumData IS NULL, '', sEnumData),
@@ -259,6 +267,7 @@ POV_LABEL: BEGIN
     call createTmpTable(keepTabl, versioned);
     IF versioned THEN
         #-- generate statement from statement parts
+        #--  (versioned section)
         SET @stmtPOVkeepTblStr = CONCAT(
             'INSERT IGNORE INTO `', keepTabl, '` (id, _iversion) SELECT entity_id AS id, _iversion FROM ', data,
             ' as data', IF(propertiesTable IS NULL, '', CONCAT(
@@ -299,7 +308,14 @@ POV_LABEL: BEGIN
         DEALLOCATE PREPARE stmtPOVkeepTbl;
     ELSE
         #-- generate statement from statement parts
-        SET @stmtPOVkeepTblStr = CONCAT('INSERT IGNORE INTO `', keepTabl, '` (id) SELECT DISTINCT entity_id AS id FROM ', data, ' as data', IF(propertiesTable IS NULL, '', CONCAT(' WHERE EXISTS (Select 1 from `', propertiesTable, '` AS prop WHERE prop.id = data.property_id AND (prop.id2=data.entity_id OR prop.id2=0))')));
+        SET @stmtPOVkeepTblStr = CONCAT(
+            'INSERT IGNORE INTO `', keepTabl,
+            '` (id) SELECT DISTINCT entity_id AS id FROM ', data, ' as data',
+            IF(propertiesTable IS NULL, '',
+                CONCAT(' WHERE EXISTS (Select 1 from `', propertiesTable,
+                        '` AS prop WHERE prop.id = data.property_id AND
+                        (prop.id2=data.entity_id OR prop.id2=0))')));
+        #--  (unversioned section)
 
         SET @stmtPOVStr = CONCAT(
                 IF(targetSet IS NULL,