DOC: update POV docs

procedures/query/applyPOV.sql

@@ -36,31 +36,29 @@ 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).
-
-
- TODO description of sourceSet and targetSet is insufficient!
  */
-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), /* (?) Name of a tmp table that contains all ids of children of the value interpreted as entity */
+                                 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 */

procedures/query/initPOV.sql

@@ -60,8 +60,14 @@ BEGIN
         SELECT conv( concat( substring(uid,16,3), substring(uid,10,4), substring(uid,1,8)),16,10) div 10000 - (141427 * 24 * 60 * 60 * 1000) as current_mills INTO t1 from (select uuid() uid) as alias;
         call createTmpTable2(propertiesTable);
 
-        -- fill in all properties named "PropertyName"
-		-- what are overwrites needed for?
+        -- Fill in all properties (plus the domain id and entity id) named
+        -- "PropertyName", be it their default name or their overridden name.
+        -- We need *all* properties (mind, the properties of entities not
+        -- abstract properties) with the given name. If an abstract
+        -- property has the name "person" it might have the name "author" in
+        -- the "Article" record type. Now, if I want to collect all properties
+        -- of the Article named "author" I need to look into the name_overrides
+        -- table.
         SET @initPOVPropertiesTableStmt1 = CONCAT('INSERT IGNORE INTO `', propertiesTable, '` (id, id2, domain) SELECT property_id, entity_id, domain_id from name_overrides WHERE name = ? UNION ALL SELECT entity_id, domain_id, 0 FROM name_data WHERE value = ?;');
         PREPARE stmt FROM @initPOVPropertiesTableStmt1;
         SET @PropertyName = PropertyName;

procedures/query/initSubEntity.sql

@@ -25,16 +25,10 @@ DROP PROCEDURE IF EXISTS db_5_0.initSubEntity;
 
 DELIMITER //
 /*
-* This procedures composes a table with the ids of all entities with the given
- * name and all their children (!!)
-* and if provided adds the supplied entity id.
-* 
-* The table name has to be provided.
-*/
-
-/*
- * Initialize a new temporary table by loading an entity and all of its children
- * into the table (i.e. their internal ids).
+ * Initialize a new temporary table by loading an entity (by name or by id or
+ * both) and all of its children into the table (i.e. their internal ids).
+ *
+ * The table name has to be provided.
  *
  * This is used by initPOVRefidsTable and initBackReference for sub-property filtering.
  *